Create a runner group

Decide which repositories, refs and events may reach a set of self-hosted runners, then change or delete the group.

Last updated 18 November 2026View as Markdown

Labels send a job to a machine; a runner group decides whether the run's code may reach that machine at all. A runner without a group is in Default, which takes any run its labels match, from any repository and any branch, pull requests included. Whoever can push a branch decides what that branch's runs execute, so keep runners that hold deploy or secret-manager credentials in a group that takes protected branches only. See Runners and runner groups.

Replace group-id with the group's id.

Prerequisites

  • ci:ManageRunners on all of CI (rn:ews::<organization id>:ci:*) to create, change or delete a group. Without it the console's New group says "Creating a runner group needs ci:ManageRunners."
  • In the console, also ci:DescribeRunners on all of CI to open Runners; without it the page shows an access-denied notice.

Create the group

The console and the API start from different settings: a new group in the console takes protected branches only and no pull requests until you change that; through the CLI, the API or Terraform, a field you leave out means every ref and pull requests allowed.

  1. Open Runners under CI.
  2. Under Runner groups, choose New group.
  3. For Name, enter deploy.
  4. Under Repositories, keep All repositories of the organization selected, or clear it and select the repositories.
  5. Keep Protected branches only selected for runners that hold deploy or secret-manager credentials, or clear it.
  6. (Optional) For Refs (optional), enter comma-separated globs such as main, release/*, refs/tags/v*. A name means a branch; start with refs/ for tags.
  7. (Optional) Select Take pull-request runs.
  8. Choose Save group.

The group appears in the Runner groups table with its repositories, what it Runs from, and how many runners it holds.

A name has 1 to 100 characters (letters, digits, spaces, ., _, -, starting with a letter or digit). A ref glob has letters, digits and * . _ / -, up to 200 characters, up to 50 globs; a group lists up to 500 repositories.

Result

A run reaches a runner of the group only when its repository, its ref and its event are all allowed. A merge queue build counts as the branch it lands on. A group with no runners takes nothing; put runners in it when you register them (see Register a runner) or move them there (see Move or disable a runner).

  • 409 "A runner group with that name exists" when the name is taken.
  • 404 "Repository not found" when a repository in the list is not in your organization.

Change the group

  1. Open Runners under CI.
  2. In the group's row menu, choose Edit group.
  3. Change the settings, then choose Save group.

Delete the group

A group that still has runners cannot be deleted, disabled runners included: its runners would otherwise fall back to Default. Move every runner out first (see Move or disable a runner).

  1. Open Runners under CI.
  2. In the group's row menu, choose Delete group.
  3. Choose Delete.

409 "Move the runners in this group (disabled ones too) to another group, or remove them, before deleting it" answers a group that still has a runner, a disabled one included. The console offers no menu for a disabled runner, so move a disabled runner out with dcloud ci runners set-group or the API.

Did this page help you?