ci-runner-indirection
The headline lesson: put the provider behind a variable once, then migrate. A literal label such
as runs-on: ubuntu-latest is copied into every workflow, so each provider change is a fleet-wide
edit. A variable with a default turns the next change into one setting per repository.
The pattern
runs-on: ${{ vars.CI_RUNNER || 'boat' }} # ordinary jobs
runs-on: ${{ vars.CI_RUNNER_LARGE || 'boat-8' }} # heavy builds
- The default keeps the workflow valid when the variable is unset.
- Set the variable only where it is unset, so a deliberate override survives a re-run.
- Use two variables, not one. A large job needs a different label than an ordinary job.
Rollout
- Count first. List every
runs-onvalue across the fleet and group them by provider. - Run a codemod that rewrites only literal Linux labels. Dry-run first and read the counts.
- Open one issue and one pull request per repository. Keep each PR small.
- Have a second model review each diff before merge. Post the review against the head commit.
- Merge only when the merge gate passes at that exact commit.
- Do the work on a cloud box, not on a laptop. Clone, rewrite, validate and push there.
What the codemod must not touch
- macOS and Windows labels. Keep them for repositories that ship native apps.
matrixvalues, list values and existing expressions.- Lines inside
run: |block scalars. A heredoc can contain the textruns-on:. -armlabels such asubuntu-24.04-arm. A variable default would drop the architecture.- Jobs that must stay hosted, for example a secret-heavy deploy or alert, or an action that resolves paths from the runner home. Put the hosted label back by hand.
It cannot see JSON-style keys such as "runs-on": "boat". Search for them after the rewrite.
Traps seen in a real migration
- Tests that assert the label. An end-to-end spec or a Python check read
runs-onand compared it to the literal string. The rewrite broke them. Search the tests forruns-onand update them to expect the expression. - A stale branch after main moves. A rebase can conflict in a file that main changed. Read both sides of each conflict. Keep main's change and re-apply only the label rewrite. Never take one side of a whole file, because that drops unrelated edits.
- Policy labels. A check may require a human-applied label for workflow edits. Do not apply a gate label to your own PR. Ask the owner.
- Old failures. A check that already fails on the default branch is not caused by your PR. Prove it from the run history, then report it. Do not bypass the gate.
- A rate limit that looks like a verdict. The GitHub API allows 5000 calls per hour per user, shared across every tool. A limited call returns a 403 or 429 error. A tool that swallows the error can show empty check lists. Treat that as "not measured" and wait for the reset.
- Reviews bind to a commit. A fix push needs a new review at the new head commit.
- Concurrency cancels. A cancelled
pr-standardsrun after a quick second push is benign.
Verify
- Run
actionlinton each changed workflow. - Run the repository's tests that read workflow files.
- After merge, confirm one run per repository picked the expected runner.