# 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](runners-and-groups.md).

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.

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

**CLI**
```sh
dcloud ci runner-groups create --name deploy --protected-refs-only
```

**API**
```http
POST /ci/api/runner-groups
{ "name": "deploy", "protectedRefsOnly": true, "allowPullRequests": false }
```

The answer is `201` with the group.

**Terraform**
```hcl
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](register-a-runner.md))
or move them there (see [Move or disable a runner](move-or-disable-a-runner.md)).

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

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

**CLI**
```sh
dcloud ci runner-groups update group-id --refs main --refs 'release/*'
```

**API**
```http
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`.

**Terraform**
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](move-or-disable-a-runner.md)).

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

**CLI**
```sh
dcloud ci runner-groups delete group-id
```

**API**
```http
DELETE /ci/api/runner-groups/group-id
```

**Terraform**
Remove 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.

## Related

- [Runners and runner groups](runners-and-groups.md)
- [Register a runner](register-a-runner.md)
- `ci.runner-groups.create` · `dcloud ci runner-groups create` · `dcloud_ci_runner_group`
