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.

Last updated 18 November 2026View as Markdown

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

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.

Did this page help you?