Documentation · Getting started

Moving from GitHub-hosted runners

The label mapping table, what to check before widening the change, and what a mistyped label does: refused on your Runners page, or left waiting by GitHub.

The change is runs-on:. Everything else in a workflow stays as it is: your actions, secrets, environments, OIDC, matrix builds, reusable workflows, status checks, branch protection, and the logs in the Actions tab.

 jobs:
   build:
-    runs-on: ubuntu-latest
+    runs-on: ghwarp-2vcpu-ubuntu-2404
     steps:
       - uses: actions/checkout@v4
       - run: make test

Before that line does anything you need the GitHub App installed on the organisation or personal account that owns the repository, and a card on file — the quickstart has both.

All of ours are Ubuntu 24.04 on x64. If you are on ubuntu-22.04 today, moving also moves you to 24.04, which is the one change here that can affect a build: check for anything pinned to a 22.04 system package.

The columns are ours. We have deliberately not printed GitHub's specifications beside them — their runner sizes change, and a table that quietly goes stale about somebody else's product is worse than one that does not try. Compare against their runner documentation and against our comparison page, which is dated and rebuilt from their docs.

Repositories in the dashboard lists the repositories the App can see, and Open a migration pull request beside one opens a draft pull request that changes only the runs-on lines naming ubuntu-latest, ubuntu-24.04, ubuntu-22.04 or ubuntu-20.04, each to ghwarp-2vcpu-ubuntu-2404. Nothing else in the workflow changes. The pull request's own checks run with the new label, so they show whether the move works before you merge it. A job on 20.04 or 22.04 moves to 24.04 with it, so read the check below about pinned packages before you merge.

An owner or an admin can open one. It needs the App's write permissions on the repository (Contents, Pull requests and Workflows). Where the installation has not granted them, the page shows the change as a patch to apply yourself instead.

runs-on is per job, so nothing forces an all-at-once migration. Change one job in one workflow, watch it, and widen from there. A matrix can name ours in one dimension and GitHub's in another and will split across both fleets.

Keep Windows and macOS jobs where they are. There is no equivalent here and there is no penalty for a workflow that uses both.

• /dev/kvm. Nested virtualisation is not available, so an Android emulator or a nested hypervisor will not start. Docker containers are unaffected.

• Anything pinned to a 22.04 package version.

• Self-hosted-runner assumptions. From GitHub's point of view ours are self-hosted runners, so a workflow with if: github.runner_environment == 'github-hosted' or similar will take the other branch.

• Caching. actions/cache needs no change — see the Actions cache. If your build is slow because of an on-disk tool cache rather than a keyed archive, look at sticky disks.

Look at the Runners page in the dashboard first. What happened depends on the label's prefix, which matches in any letter case: GHWarp- is ours too.

• A label that starts with ghwarp- but is not one we sell — a typo such as ubuntu-2204 where ubuntu-2404 was meant — is refused. The job appears on your Runners page as refused, with the label you wrote and a link to the list of labels.

• Our label beside anything else — self-hosted, linux, or a second label of ours — is refused the same way. Put our label in runs-on on its own.

• A label that does not start with ghwarp- is not addressed to us, so we never see the job and it does not appear on your Runners page. It waits for a runner that is not coming until GitHub times it out, which looks like an outage and is almost always a typo in the prefix.

After a refusal, GitHub may go on showing the job as waiting for a runner. We ask GitHub to cancel the run only when every job on it was one we refused, and only if our GitHub App has the actions: write permission; otherwise the job waits until GitHub times it out, or until you cancel the run. Check the label against the list, which also says what a refusal does to the rest of the run.