# Runners and runner groups

Which machines take which jobs: runners you register, runner pools the platform starts, labels, and the groups that decide whose code may reach a machine.

Every run gets a machine. Linux runs get a platform machine created for the run unless a job asks
for something else; the rest go to machines you register (**runners**) or to machines the platform
starts in your organization for your jobs (**runner pools**).

## Runners

A runner is a machine you own, registered to your organization with a one-time token (see
[Register a runner](register-a-runner.md)). It connects out to Deutsche Cloud; nothing connects in to
it. It runs one of two programs, shown in the **Agent** column of **Runners** (the column is
hidden while all your runners run the same one):

| Program           | Takes                                                                                                             |
| ----------------- | ----------------------------------------------------------------------------------------------------------------- |
| GitHub runner     | Jobs of GitHub-syntax workflows, one job at a time, on Linux, macOS or Windows                                    |
| Deutsche Cloud agent | Whole runs of native-format workflows, on a Mac (see [Connect a Mac](connect-a-mac.md)); never GitHub-syntax runs |

A runner registered with a token for one repository serves that repository only.

## Labels

A job names labels with `runs-on`, and a runner carries labels. A runner keeps the labels it
reports about itself (`self-hosted`, its operating system, its architecture). Its other labels are
those the registration token fixed, or else those the machine declared. A Mac cannot carry a Linux
or Windows label, and a Linux machine cannot carry a macOS label.

- A GitHub-syntax job goes to a runner that carries every label in its `runs-on`, compared without
  regard to case.
- A native run goes to a Deutsche Cloud agent whose labels include the `runs-on` of every job of the
  run. A run whose jobs are all `linux` never goes to a runner.
- A Mac takes only jobs that ask for macOS: `runs-on: macos`, `macos-*` or a label only Macs carry.
  A job asking only for `self-hosted` or `arm64` never reaches it.

## Runner groups

A group decides whether a run's code may reach its runners: which repositories, which refs
(branch globs, or `refs/tags/…` for tags), only branches a branch protection rule covers, and
whether pull request runs may. A merge queue build counts as the branch it lands on. A runner
without a group is in **Default**, which takes any run its labels match. See
[Create a runner group](create-a-runner-group.md).

There are no forks: whoever can push a branch decides what that branch's runs execute, through a
push as much as through a pull request. Keep deploy or secret-manager credentials only on runners in
a group that takes protected branches only.

## Runner pools

A runner pool is a set of machines of one size that the platform starts in your organization when
GitHub-syntax jobs with the pool's labels wait, and stops when the work is done. Each machine runs
GitHub's runner and takes one job at a time. A job whose `runs-on` labels are all among the pool's
goes there, `self-hosted` or not (a pool also counts as `self-hosted`, `linux` and `x64`); when
several pools match, the one with the fewest labels beyond the job's wins. See
[Create a runner pool](create-a-runner-pool.md).

## Waiting for a runner

A run or job that needs a runner waits for one. The waiting reason says which label it needs and
whether a matching runner is registered, offline or busy.

- When no runner with the labels is online, it fails after 20 minutes with
  `no online runner with label …`.
- When one is online but busy, it waits for it. A run still queued two hours after it was queued
  fails with the same message.

A runner is **Offline** once it has not reported for five minutes. A run a Deutsche Cloud agent was
executing fails five minutes after that agent's last report.

## Related

- [Register a runner](register-a-runner.md)
- [Workflows and runs](workflows-and-runs.md)
- [Security in CI](security.md)
