Runner sizes and labels

Documentation / Run jobs

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 example battleship-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.

LabelvCPUMemoryDiskGitHub runner it follows
battleship-slim15 GiB14 GBubuntu-slim; jobs are limited to 15 minutes
battleship-latest, battleship-ubuntu-latest412 GiB20 GBubuntu-latest
battleship-standard48 GiB40 GBThe standard Linux size
battleship-2core28 GiB75 GB2-core larger runner
battleship-4core416 GiB150 GB4-core larger runner
battleship-8core832 GiB300 GB8-core larger runner
battleship-16core1664 GiB600 GB16-core larger runner
battleship-32core32128 GiB1200 GB32-core larger runner
battleship-64core64256 GiB2040 GB64-core larger runner
battleship-96core96384 GiB2040 GB96-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-4core

To 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-4core

enginebox-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.

The source repository is private. Source access is by request.

Search concepts, guides and command examples.