Migrate from GitHub-hosted runners

The full migration guide: what actually changes, the three migration paths, the exact label mapping the Migrate Runners tool applies, what the PRs contain, verification, and rollback.

Migrating to Latchkey runners is a routing change, not a rewrite. The runs-on: label is the only thing that decides which runner takes a job, so it is the only thing a migration touches. Everything else keeps working exactly as before: the actions you call, the secrets GitHub injects, your environments and protection rules, and caches on GitHub's side. And GitHub-hosted labels keep working alongside latchkey-* labels, so nothing forces a full cutover.

What changes, and what keeps working#

Before you start#

Three ways to migrate#

The three paths compose: most teams hand-edit one workflow as a pilot, bulk-migrate with the tool, and reach for AI Scan on the handful of repositories that deserve their own image.

Path 1: the Migrate Runners tool#

The tool has two entry points, and both open the same modal: the Migrate Runners item in the dashboard sidebar, and the CTA in the Runner Types card footer on the Runners page. Opening migration PRs requires an owner or admin role.

Nothing in a repository changes until your team merges its pull request. If a repository already has an open migration PR, the tool links to it instead of opening a duplicate; if there is nothing left to switch, it shows a Nothing to migrate state. With more than 20 repositories to move, migrate in passes.

The exact mapping the tool applies#

The untouched rows are deliberate: jobs the tool cannot confidently route keep running exactly where they run today, so you can migrate your Linux fleet now and leave mixed-OS workflows safely intact. Anything the tool skips can still be moved by hand whenever you are ready.

What each pull request contains#

Each PR rewrites the runs-on: lines and nothing else; as the PR body itself puts it, "Only runs-on: lines were touched. Every other line in each file is byte-identical." The one exception: when the migration also injects Latchkey cache steps, those steps are the only additions beyond the runs-on lines, and the body says so. A before and after mapping table for each file shows exactly what changed, so review takes minutes, not days.

Path 2: hand-edit a single workflow#

For one workflow the change is one line per job, and both label forms route identically:

jobs:
  test:
    runs-on: latchkey-small

jobs:
  test:
    runs-on: [self-hosted, latchkey-small]

The step-by-step version of this path, including verifying the first run and picking a size, is Run your first job.

Path 3: AI Scan, for repos that deserve their own image#

Some repositories are worth more than a label swap. AI Scan reads the workflows a repository actually runs and proposes a custom runner configuration with a right-sized shape and an image that preinstalls the repo's toolchain, so jobs skip their setup steps entirely. If that sounds like one of yours, start at Custom runners with AI Scan and migrate that repository to its custom label instead of a preset.

An incremental strategy#

You do not need a big-bang migration, and we suggest avoiding one. Start with one low-risk repository, ideally a flaky or slow one where cheaper minutes, faster pickup, and self-healing are most visible, and let it run for a week before you commit the fleet.

Jobs that need GPU, Windows, macOS, or arm64 hosts stay on GitHub-hosted or other runners, and that is fine indefinitely: runs-on is decided per job, so a workflow can mix Latchkey and GitHub-hosted jobs freely.

Verify after merging#

Rolling back#

Rollback is the same one-line change in reverse: revert the migration PR and jobs route back to GitHub-hosted runners immediately. There is nothing else to undo, no agent to uninstall and no configuration to clean up, and the repository stays monitored, so your analytics continue either way.

Common questions#