Create a runner group
Decide which repositories, refs and events may reach a set of self-hosted runners, then change or delete the group.
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:ManageRunnerson 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:DescribeRunnerson 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.
- Open Runners under CI.
- Under Runner groups, choose New group.
- For Name, enter deploy.
- Under Repositories, keep All repositories of the organization selected, or clear it and select the repositories.
- Keep Protected branches only selected for runners that hold deploy or secret-manager credentials, or clear it.
- (Optional) For Refs (optional), enter comma-separated globs such as
main, release/*, refs/tags/v*. A name means a branch; start withrefs/for tags. - (Optional) Select Take pull-request runs.
- Choose Save group.
The group appears in the Runner groups table with its repositories, what it Runs from, and how many runners it holds.
dcloud ci runner-groups create --name deploy --protected-refs-onlyPOST /ci/api/runner-groups
{ "name": "deploy", "protectedRefsOnly": true, "allowPullRequests": false }The answer is 201 with the group.
resource "dcloud_ci_runner_group" "deploy" {
name = "deploy"
protected_refs_only = true
allow_pull_requests = false
}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
- Open Runners under CI.
- In the group's row menu, choose Edit group.
- Change the settings, then choose Save group.
dcloud ci runner-groups update group-id --refs main --refs 'release/*'PATCH /ci/api/runner-groups/group-id
{ "refs": ["main", "release/*"] }A field you leave out keeps its value; repositoryIds: null means every repository again. A body
that changes nothing answers 400.
Change the arguments of the dcloud_ci_runner_group resource and apply.
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).
- Open Runners under CI.
- In the group's row menu, choose Delete group.
- Choose Delete.
dcloud ci runner-groups delete group-idDELETE /ci/api/runner-groups/group-idRemove the dcloud_ci_runner_group resource from your configuration and apply.
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.