Runner sizes and labels
Choose how much CPU, memory and disk a job gets by label, and see how sizes share the machine.
How a job finds a runner
A job reaches your machine through the labels in its runs-on. GitHub offers the job to your machine’s runners when the job’s repository is allowed in their runner group.
- Every pool has its own label,
battleship-<pool-id>, for examplebattleship-linux. - A pool that declares a size also answers that size’s label, for example
battleship-4core.
All labels a job requests must match the pool. A job matches by pool label first, otherwise by size label.
Labels written with the earlier enginebox- prefix, such as enginebox-4core, still work and name the same pools and sizes. battleship-ubuntu-latest is another name for battleship-latest, and it is the default: the size to use when you only want what ubuntu-latest gave you. Labels are matched without regard to upper and lower case.
Linux x64 sizes
A size is a request for vCPU, memory and disk. The names follow GitHub’s hosted and larger runners, so a workflow can switch by changing a label. Disk is a thin-provisioned quota for the runner’s root disk.
| Label | vCPU | Memory | Disk | GitHub runner it follows |
|---|---|---|---|---|
battleship-slim | 1 | 5 GiB | 14 GB | ubuntu-slim; jobs are limited to 15 minutes |
battleship-latest, battleship-ubuntu-latest | 4 | 12 GiB | 20 GB | ubuntu-latest |
battleship-standard | 4 | 8 GiB | 40 GB | The standard Linux size |
battleship-2core | 2 | 8 GiB | 75 GB | 2-core larger runner |
battleship-4core | 4 | 16 GiB | 150 GB | 4-core larger runner |
battleship-8core | 8 | 32 GiB | 300 GB | 8-core larger runner |
battleship-16core | 16 | 64 GiB | 600 GB | 16-core larger runner |
battleship-32core | 32 | 128 GiB | 1200 GB | 32-core larger runner |
battleship-64core | 64 | 256 GiB | 2040 GB | 64-core larger runner |
battleship-96core | 96 | 384 GiB | 2040 GB | 96-core larger runner |
Which sizes your machine serves depends on its capacity and on the pools configured for it. Run one of your jobs on a size before you rely on it. Machines lists the ship classes these sizes are booked against.
A vCPU is one hardware thread of the machine. A Frigate, with 8 cores and 16 threads, has 16 threads for runners to book. Only your organisation’s jobs run on the machine, so the only work a job shares its threads and memory with is your own.
The disk of a size belongs to that one job. It is deleted with the job’s virtual machine.
Target a size
Name the size label:
runs-on: battleship-4coreTo name a runner group as well, for an organisation that restricts the group to chosen repositories, write both:
runs-on:
group: enginebox-ci
labels: battleship-4coreenginebox-ci is an example group name. A job that asks for a size no pool on your machine serves is recorded as waiting and no runner is started for it. It stays queued in GitHub until a pool serves that size or GitHub cancels it after 24 hours. A label that is not in the table above matches nothing, and the job waits in GitHub in the same way.
How many jobs run at once
The machine has a budget of vCPU, memory and disk. Each running job books its size against that budget, and a job starts only when its size fits what is left. A pool also has a runner limit, at most 16.
Memory usually decides the count. For example, a 112 GiB memory budget holds seven 16 GiB runners or fourteen 8 GiB runners. Choose the smallest size your job passes on, and keep the larger label for jobs that need the memory.
After moving a job to a smaller size, watch for out-of-memory kills in the job and for jobs that fail where they passed before. Usage explains how to tell from the machine’s history whether you need a bigger machine or another one.
Adjusting a size for one machine
The machine’s operator can change the memory and disk of a size for that machine, from half to twice the catalogued value, with size_overrides in the controller’s GitHub configuration. vCPU cannot be changed this way. The change applies to runners started afterwards; running jobs keep their virtual machines.
arm64, GPU, Windows and macOS
Runners are Linux x64. There are no arm64, GPU, Windows or macOS runners. A job that asks for one of those waits and never starts, so keep those jobs on GitHub-hosted runners.