Create a runner pool

Have the platform start machines in your organization for GitHub-syntax jobs with the pool's labels, one job per machine, and stop them when the work is done.

Last updated 19 November 2026View as Markdown

A pool's machines run GitHub's runner on Ubuntu 24.04 with Docker (with Compose and Buildx), git, git-lfs, jq, a compiler, Python, gh and passwordless sudo for the user runner. Give a pool ubuntu-latest and ubuntu-24.04, and the jobs that would run on the one-machine-per-run hosted machines run on per-job machines instead, each with its own token and the GitHub API (see Call the GitHub API from a job).

Important

The pool's machines are instances of your organization, billed as instances while they run. Always on machines (minSize) cost money even when no job waits.

Prerequisites

  • ci:CreateRunnerPool on all of CI (rn:ews::<organization id>:ci:*), and what the pool launches with: autoscaling:CreateLaunchTemplate, autoscaling:CreateAutoScalingGroup and ec2:RunInstances. A missing one answers 403 "Not allowed: …".
  • Room in the Auto Scaling quotas for one group and one launch template.
  • In the console, also ci:DescribeRunners to open Runners (without it the page shows an access-denied notice) and ci:DescribeRunnerPools to see Runner pools on it.

Create the pool

  1. Open Runners under CI.
  2. Under Runner pools, choose New pool.
  3. For Name, enter linux.
  4. For Labels, keep ubuntu-latest, ubuntu-24.04 or enter your own, comma-separated.
  5. For Machine, choose a size.
  6. For Always on, At most and Spare, enter the numbers of machines.
  7. Under Machine reuse, choose Per repository, Shared across repositories for trusted jobs or Fresh machine per job.
  8. (Optional) Clear Pre-built runner image.
  9. Choose Create pool.

Beside the button the dialog shows what the settings cost an hour at most, and a month for the always-on machines.

Through the CLI (--runner-group-id) or the API (runnerGroupId), and not in the console, you can tie the pool to a runner group, whose repository and ref rules then decide which runs reach it.

The console starts a new pool at size s-4, 0 always on, 5 at most and 0 spare; through the CLI or the API, minSize and spare default to 0 and maxSize and size are required. Sizes a-2 to a-16 are ARM machines: give such a pool the label ubuntu-24.04-arm.

  • 400 "minSize is above maxSize".
  • 400 "A Linux machine cannot carry the label macos-latest: it would be sent macOS jobs."
  • 409 "A runner pool named linux exists".
  • 404 "Runner group not found".

Result

The pool is an auto scaling group and a launch template named runner-pool-linux in your organization; its row menu has Open its auto scaling group. When a job for its labels is queued, and every minute besides, the pool asks for as many machines as jobs run and wait, plus the spare ones, between Always on and At most. The Scaling column shows how many it wants now. An idle machine stays until the last five minutes of its paid hour, so the next job starts on it at once, and then goes.

How machines are reused:

Machine reuse A machine takes
Per repository (the default) Later jobs of the repository of its first job, of the same kind: pull request and merge queue jobs, or the rest
Shared across repositories for trusted jobs Default branch, tag, manual and scheduled jobs of every repository; pull request jobs stay per repository
Fresh machine per job (cleanMachinePerJob) One job, then it is destroyed

A job with an environment: or permissions: id-token: write is always its machine's last. Between jobs, every container, network and volume a job left is removed and the work directory emptied.

Where the machines run

Each machine the pool starts goes to the platform's own servers in the region when one has room, and to your organization's cloud provider when they are full. The choice is made for every machine as it starts, so one burst can run partly on both. On the run page, each job says where it ran: "Ran on own host …", or "Ran in the cloud" with the reason, for example "… full (3 of 3 runner slots in use)". The machine is an instance of your organization either way and shows in EC2 with its zone and the tag ews:placement.

On the platform's servers a machine boots from a runner image with Docker and GitHub's runner installed (often a machine already parked there, so the job starts within seconds), and after its last job it waits up to 30 minutes for the next job of its repository, which then finds its Docker images, package caches and checkout on the disk. It leaves earlier when another job needs the room.

To keep every machine at your organization's provider, create the pool with placement set to cloud-only (CLI: --placement cloud-only); change it later with Change or delete a runner pool. Machines already running stay where they are.

With Pre-built runner image on (the default), machines boot from an image of your organization with everything installed, built once per region and architecture by a small builder machine, and take their first job about a minute sooner. Until it is ready, or after a failed build (retried after six hours), machines boot stock Ubuntu and install at boot. It is rebuilt weekly. The builder and the image's storage are billed to you.

Did this page help you?