Disclosure: This guide is from the Sengi team and was written with AI. Sengi is the managed runner service used in the example.
A runner change can be a small pull request, but a small diff does not mean every job will behave identically. The machine still needs the right operating system, tool versions and container environment.
Before moving a Linux job, check these assumptions. The goal is a first successful result you can compare with your existing run, not a repository-wide rewrite.
Check what the label actually selects
GitHub uses runs-on to choose a machine. An array is an intersection: the runner must match every listed label. Adding a new provider's label to an old array is not the same as replacing the target. GitHub explains label matching here.
For Sengi, a supported target is a complete label:
runs-on: sengi-standard-2-ubuntu-2404
Use the provider's documented form rather than inventing combinations. If the selection comes from a matrix, an expression or a reusable workflow, inspect where that value is defined before changing it.
Sengi currently offers Ubuntu 24.04 on x64. Leave Windows, macOS, arm64 and jobs requiring another operating-system image on their existing runners. A job on ubuntu-latest also needs an image check: switching to a fixed Ubuntu 24.04 target may change an assumption about what “latest” supplies. Sengi's migration instructions identify the supported targets.
Make tool dependencies explicit
A working build can quietly depend on software that happens to be installed on its current runner. Look for commands such as node, python, ruby, java, docker and native compilers. For each important dependency, identify how the workflow selects its version.
Prefer an existing setup step or your project's documented installation procedure over relying on whichever executable appears first in the machine's path. Keep the dependency lockfile and install command unchanged for the first comparison. Otherwise, a runner migration and a dependency upgrade become one experiment that is harder to diagnose.
If you need a diagnostic step, print only the relevant tool versions. Do not dump the whole environment: CI logs can contain sensitive information, and a version check does not require exposing secrets.
Treat containers as a separate compatibility check
A job-level container: setting changes where script steps execute. Check the image, registry access and shell assumptions as well as the host runner. GitHub's container documentation notes that the default shell inside a job container is sh, not bash; an explicit shell can override it. It also warns that Docker Hub's normal pull limits can affect self-hosted runners. Read the container behavior.
Do not remove registry authentication or alter service-container networking merely to make a migration look like a one-line change. Keep those settings intact, then inspect the first result on the chosen runner. A failure while pulling an image and a failure in your test suite need different fixes.
Separate routing trouble from a failed step
If the job never starts, inspect the exact label, repository connection and available capacity. If it starts and fails, inspect the first failing step and compare it with the previous run. Changing five unrelated settings at once usually destroys the useful comparison.
For Sengi, connect the repository to a project through Connect GitHub before merging its runner-label change. Installing the GitHub App alone is not the complete connection. The current migration guide walks through that sequence.
Keep the first trial reversible
Choose one representative build or test job. Review the pull request, let its normal trigger run, then compare the result, artifacts and required checks. Only widen the change once that job behaves as expected.
Keep the original label in the pull-request diff so rollback is a simple revert. A green first run is useful evidence; it is not proof that every job in a large matrix has the same requirements.
That is the practical benefit of keeping GitHub Actions while changing execution services: you can test the machine choice without replacing the workflow system. Start small, preserve the comparison, and expand based on actual results.
Top comments (0)