Home / Blog / Runners and limits
How hard is it to switch GitHub Actions runners, and what breaks?
Switching a job to another runner is usually one runs-on line. What breaks is the image, size, Docker, IP allowlists, limits and billing. A checklist, and a rollback with no commit.
Switching a job to another runner is usually one line: you change runs-on and the rest of the workflow stays as it is. What breaks is everything the old label stood for. Check 7 things before you widen the change: the image’s tools, its CPU, memory and disk, Docker, conditions on the runner’s kind, IP allowlists, limits, and billing. Move one job first, and keep the old label one revert away. Our GitHub Actions runner size guide compares the sizes.
- Usually only runs-on changes; actions, secrets, environments and required checks stay as they are.
- Check 7 things: image tools, CPU, memory and disk, Docker, runner.environment conditions, IP allowlists, limits and billing.
- GitHub does not recommend allowlisting its hosted-runner IP ranges, because they are not dedicated to Actions.
- runs-on can read a repository variable, so a job moves when the variable is set and moves back when it is deleted.
- Move one job first and compare a run on each label before you move the next.
This post is the generic answer, for any runner you can point a label at. It lists what to check, how, and the one pattern that makes the move reversible without a commit. Every figure and quotation about GitHub is from GitHub’s own pages, read on the date this post was last checked. For how our own labels map to GitHub’s, read the migration page; this page does not make that claim for any other runner.
What does switching runners change in a workflow?
Only the value of jobs.<job_id>.runs-on. GitHub accepts a single string, a single variable holding a string, an array of strings or variables, or a group or labels key. With an array the job runs on a runner that matches every value, so [self-hosted, linux, x64, gpu] means a runner with all four labels. A label that matches no runner is not refused by GitHub: the job is queued for a runner that is not coming, which is why a typo in a label looks like an outage (the waiting-for-a-runner guide has the checks).
A runs-on change edits no action, secret, environment, branch rule or required status check. What can change is how a job behaves once it has a machine.
What breaks when you switch, and how do you check each one?
| What differs | What can go wrong | How to check |
|---|---|---|
| The image: preinstalled tools and their versions | A tool the old runner shipped is missing, or is a different version. GitHub-hosted jobs start from a fresh instance of the image named by runs-on, and the job's Set up job step records the runner image and links the list of preinstalled tools. | Print the versions the job relies on in the first step and compare them with a known-good run. |
| Size: CPU, memory and disk | GitHub's standard Linux runner has 2 vCPU, 8 GB of memory and 14 GB of SSD in a private repository, and 4 vCPU, 16 GB and 14 GB in a public one. Another runner's numbers are its own. | Run nproc, free -m and df -h in the job, and read the peak memory of the slowest job before you move it. |
| Docker and containers | GitHub says container actions and service containers on a self-hosted runner need a Linux machine with Docker installed. GitHub's single-CPU ubuntu-slim runner is an unprivileged container, so Docker-in-Docker is not supported there. A container job's default shell is sh, not bash. | Run docker version and one real build in the new job before you widen. |
| Conditions that ask what kind of runner this is | The runner.environment context is github-hosted for GitHub's runners and self-hosted for self-hosted runners configured by the repository owner. If the new runner is one you register, an if: that tests for github-hosted takes the other branch. | Search the workflows for runner.environment, and for self-hosted in any runs-on array. |
| IP allowlists | GitHub's published ranges for hosted runners are not dedicated to Actions, and GitHub does not recommend allowlisting them. A different runner connects from different addresses. | Ask which addresses the new runner uses, and whether they are yours alone or shared, before you change a firewall rule. |
| Limits and queueing | GitHub-hosted jobs stop at 6 hours (15 minutes on single-CPU ubuntu-slim), and concurrency depends on the plan (20 jobs on Free, 40 on Pro, 60 on Team, 500 on Enterprise for standard runners). A job on a self-hosted runner may run 5 days and wait 24 hours in the queue; ask which limits apply to the runner you are moving to. | Set timeout-minutes on every job you move, so the limit is your number and not a surprise. |
| Billing | Standard GitHub-hosted runners in private repositories draw on the plan's included compute usage. Self-hosted runners are free and do not reduce it. Ask the provider what it charges for the same minutes. | Read last month's usage per workflow before you move the heaviest one. |
The first row is the one that bites most often. A GitHub-hosted job starts from a fresh instance of a named image, and a different runner’s image is a different list of tools. Memory and disk are the next two: the figures above are GitHub’s own, and a runner that offers more of one and less of another will change a job that was close to a limit. The out-of-memory post covers the failures that follow, and the runner size guide covers how to choose a size. For the limits row, the limits post keeps the whole table.
What about IP allowlists and firewalls?
If anything you run, such as a database, a registry or an internal API, only accepts connections from known addresses, this is the part of the move that fails after the green check. GitHub says its hosted-runner ranges, which come from the actions key of the GET /meta API and are updated once a week, “are not dedicated to GitHub Actions” and that it does not recommend adding them to an allowlist. It recommends larger runners with a static IP address range, or self-hosted runners. So a new runner needs the same question answered: which addresses will its jobs come from, and does anyone else share them? Get that in writing from the provider, then change the firewall, and only then the label.
How do you move one job, and roll it back without a commit?
runs-on can read a repository variable, so the label does not have to be in the file. Put the new label in a variable, and the job moves when the variable is set and moves back when it is deleted. The step that prints what the runner is gives you the evidence to compare against a run on the old one.
name: CI
on:
pull_request:
push:
branches: [main]
jobs:
test:
# Set the repository variable RUNNER_LABEL to move this job. Delete the
# variable and the job is back on ubuntu-24.04, with no commit.
runs-on: ${{ vars.RUNNER_LABEL || 'ubuntu-24.04' }}
timeout-minutes: 15
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- name: What this runner is
run: |
echo "environment: ${{ runner.environment }} os: ${{ runner.os }} arch: ${{ runner.arch }}"
nproc
free -m
df -h .
git --version
docker --version
- run: npm ci
- run: npm test
This workflow passes actionlint 1.7.12, which knows that vars is available in runs-on. We have not run it on GitHub, and a variable is one value for every run of the job, so do this on one workflow at a time. Compare the printed lines, the log’s step times and the minutes of a run on each label before you move the next job.
Does anything else in the workflow file need to change?
Look for four things. A matrix whose runs-on is ${{ matrix.os }} moves in its matrix, not on the job line, and every if: that reads matrix.os or runner.os must still match. Any condition on runner.environment, as in the table. A job that names ubuntu-latest for a container or a version check: the label’s meaning is GitHub’s and moves on GitHub’s schedule (the ubuntu-latest post tracks it). And caches: read the cache hit or miss line on the first run on the new runner, as the build-cache post explains.
When is it not worth switching?
When you cannot say what you expect to gain. A runner changes three numbers: the time a job waits for a machine, the time it runs, and what each minute costs. If your wait is already short, find the slow step first (the speed guide shows how), because a runner does not shorten a download. If the bill is the reason, GitHub’s rates and the included usage are on one page, and the questions to put to any provider are in the provider guide.
runners.io is a service that runs these jobs, and the change there is the same one line. The label table, what a refused label does, and what to check before you widen are on the from-GitHub-hosted docs page and in the runner labels reference. Every size we run, with its memory, disk and rate a minute, is on our managed GitHub Actions runners page.
Sources
- Choosing the runner for a job (docs.github.com)
- GitHub-hosted runners reference (docs.github.com)
- Self-hosted runners reference (docs.github.com)
- Running jobs in a container (docs.github.com)
- Contexts reference (docs.github.com)
- Using workflow run logs (docs.github.com)
- Actions limits (docs.github.com)
- Billing and usage for GitHub Actions (docs.github.com)
Frequently asked questions
How hard is it to switch GitHub Actions runners?
Usually one line per job: you change runs-on. The work is checking what the new runner is not, such as its preinstalled tools, CPU, memory and disk, Docker support, outbound IP addresses and limits. Move one job first and compare it with a known-good run.
What breaks when you change the runs-on label?
Missing or different tools, a job that was close to a memory or disk limit, Docker features, an if: that tests runner.environment, a firewall that expects GitHub's addresses, and the limits and billing that depended on GitHub-hosted runners.
Can I allowlist GitHub-hosted runner IP addresses?
GitHub publishes the ranges in the actions key of its meta API, updated weekly, but says they are not dedicated to Actions and does not recommend allowlisting them. It recommends larger runners with a static IP range, or self-hosted runners.
How do I roll back a runner change without a commit?
Make runs-on read a repository variable with a default, such as vars.RUNNER_LABEL || 'ubuntu-24.04'. Setting the variable moves the job, and deleting it puts the job back on the default label for every later run.