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). 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); 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-onof every job of the run. A run whose jobs are alllinuxnever 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 forself-hostedorarm64never 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.
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.
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.