Docs

How to move a job to Zerun, what the beta supports, and how to move back to GitHub-hosted runners.

Before you start

You need all of these:

• A personal GitHub account. Organization accounts are not in the beta.
• A private repo. Zerun refuses public repos.
• Jobs that run on Linux x64.
• An invite to the beta. Ask for one at beta@zerun.example.

Move a job to Zerun

1. Install the Zerun GitHub App

   Sign in to the Zerun dashboard with GitHub and install the App on the private repos you choose. Zerun adds two runner labels to each repo, zerun-2cpu and zerun-4cpu.

2. Check your workflows

   Run zerun check on your repo. It lists the jobs that can move and prints the one-line change for each. See Check a workflow.

3. Buy credit and set a cap

   Buy credit in the dashboard before your first job, in packs of $10, $25 or $50. Without credit, new jobs fail within about 15 seconds with a message. The monthly cap is $20 until you change it. See pricing.

4. Change the label on a branch and push

   - runs-on: ubuntu-latest+ runs-on: zerun-4cpu

   Move test and build jobs first. Leave jobs that deploy or publish until the others pass.

5. Watch the job

   GitHub runs the job on Zerun and shows the checks as usual. The dashboard lists each job with its queue time, duration, vCPU-seconds, charge and outcome.

Check a workflow

zerun check reads workflow files and tells you which jobs can run on Zerun. It reads files on your machine and sends nothing anywhere. Beta users get the zerun command with their invite.

zerun check [--size 2|4] [--json] <workflow files or directories>

• Give it workflow files or directories. For a repo root, it reads .github/workflows.
• --size picks the label in the suggested change. It is 2 unless you give 4.
• --json prints the same report as JSON.
• It exits with 0 when it read every file, 1 when a file could not be read or parsed, and 2 for a usage error. A job that cannot move is a normal result, not an error.

For each job, it gives every runs-on value a verdict: eligible, already on Zerun, not eligible with the reason, check the called workflow, or unknown. It warns about tools that GitHub preinstalls and Zerun does not, about container jobs, and about jobs that deploy or publish. Here is a report for a workflow with two jobs:

$ zerun check --size 4 .github/workflows/test.yml
.github/workflows/test.yml
  test (line 4)
    ubuntu-latest: eligible.
    warning .github/workflows/test.yml:8: The job calls npm, which GitHub-hosted runners preinstall and the Zerun image does not. Add actions/setup-node before this step.
    change .github/workflows/test.yml:5
      - runs-on: ubuntu-latest
      + runs-on: zerun-4cpu
  release (line 10)
    macos-latest: not eligible. macOS runners are not in the beta.

1 of 2 jobs have a runs-on change.
Known differences for every job on Zerun:
  Jobs reach the internet from AWS Sydney (ap-southeast-2) addresses, not from GitHub's.
  Disk and CPU models differ from GitHub-hosted runners, so durations can differ.

What the beta supports

Zerun keeps no cache of its own between jobs. actions/cache works as it does on GitHub-hosted runners, under GitHub's own rules.

Known differences from ubuntu-latest

• The image has fewer tools. zerun check names the tools a job calls that the image lacks, and the setup-* action that installs each one when there is one.
• Jobs reach the internet from AWS addresses in Asia Pacific (Sydney), ap-southeast-2, not from GitHub's.
• Docker Hub limits anonymous pulls per IP address. If pulls from Docker Hub fail, log in to Docker Hub in the job.
• Disk and CPU models differ from GitHub-hosted runners, so durations can differ.

Limits

When something goes wrong

• A job that fails because of Zerun is not charged. The dashboard marks it as an infrastructure failure, and Zerun emails you a link to the job so you can re-run it with GitHub's re-run button. Zerun does not re-run jobs for you.
• If AWS has no capacity, jobs wait in GitHub's queue while Zerun keeps trying. After 10 minutes, Zerun emails you once with the steps to move the jobs back to GitHub-hosted runners.
• If Zerun itself is down, running jobs carry on, because they talk to GitHub directly. New jobs wait in GitHub's queue.

Turn Zerun off

GitHub fixes a run's runs-on label when the run is created. A change to the workflow therefore affects only later runs. Jobs that are already queued still need a Zerun runner.

To leave Zerun for good, do these in order:

1. Change runs-on back in every workflow that uses a Zerun label. The dashboard lists them.
2. Wait for queued Zerun jobs to finish.
3. Remove your repos from the App. That deletes their Zerun runner labels.
4. Uninstall the App.

If you uninstall the App first, GitHub revokes its access before Zerun hears about it. The labels then stay registered with no runner behind them, and jobs that target them wait in GitHub's queue. For unused credit, see the refund policy.

What Zerun can access

The App does not ask for Contents, Actions write, Checks or Pull requests, so it cannot read your code or re-run your jobs. Step logs and secrets go between the runner and GitHub, and Zerun does not receive them.

Zerun keeps a record of each job, including its repo, workflow, job name, commit SHA, timings, charge and result. It also keeps statistics such as the tree hash of the job's checkout. It never keeps your code, step logs or secrets. The privacy policy lists everything Zerun stores.