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

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](call-the-github-api-from-a-job.md)).

**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

**Console**
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.

**CLI**
```sh
dcloud ci runner-pools create --name linux --labels ubuntu-latest --labels ubuntu-24.04 \
  --size s-4 --max-size 10
```

**API**
```http
POST /ci/api/runner-pools
{ "name": "linux", "labels": ["ubuntu-latest", "ubuntu-24.04"], "size": "s-4", "maxSize": 10 }
```

The answer is `201` with the pool.

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](change-or-delete-a-runner-pool.md). 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.

## Related

- [Change or delete a runner pool](change-or-delete-a-runner-pool.md)
- [Runners and runner groups](runners-and-groups.md)
- `ci.runner-pools.create` · `dcloud ci runner-pools create`
