# Register a runner

Issue a one-time registration token and register a machine you own as a runner, with GitHub's runner on Linux or by hand on any system.

The token decides which runs the machine may take (its group, and optionally one repository) and,
when you set them, its labels; the machine cannot widen either. For a Mac that runs native-format
workflows, see [Connect a Mac](connect-a-mac.md).

## Prerequisites

- `ci:ManageRunners` on all of CI (`rn:ews::<organization id>:ci:*`) for a runner of the whole
  organization, or on the repository (`rn:ews::<organization id>:ci:repository/<repository id>`)
  for a runner of one repository. Without it the console's **Add runner** says "Adding a runner
  needs ci:ManageRunners, which your policies do not grant. Ask an administrator."
- In the console, also `ci:DescribeRunners` on all of CI to open **Runners**; without it the page
  shows an access-denied notice.
- (Optional) A runner group (see [Create a runner group](create-a-runner-group.md)).
- A machine with outbound HTTPS to the console and to your organization's Git host.

## Step 1: Issue a registration token

**Console**
1. Open **Runners** under CI, then choose **Add runner**.
2. (Optional) Select **This machine will hold deploy or secret-manager credentials**. The console
   then refuses every group that does not take protected branches only.
3. For **Runner group**, choose a group, or **Default: any repository, any branch**.
4. (Optional) For **Labels (optional)**, enter comma-separated labels such as `gpu, docker`.
5. Choose **Issue token**.

The next dialog shows the token's commands and when it expires. Copy them now: the token is shown
once and cannot be shown again. The console issues tokens for the whole organization; for a runner
of one repository, use the CLI or the API.

**CLI**
```sh
dcloud ci runners create-registration-token --group-id group-id --labels gpu
```

Add `--repository-id repo-id` for a runner of one repository.

**API**
```http
POST /ci/api/runners/registration-tokens
{ "groupId": "8a3e2c1d-4b5f-4e6a-9c7d-0e1f2a3b4c5d", "labels": ["gpu"] }
```

The answer is `200` with `token`, `expiresAt`, `runnerUrl` and the commands `linuxInstallCommand`,
`configCommand` and `installCommand`. An empty body issues a token for the whole organization and
the Default group.

The token expires 15 minutes after it is issued and registers exactly one machine; running the
command again with a spent token registers nothing.

- `404` "Runner group not found" when the group is not in your organization.
- `404` when the repository is not in your organization.

## Step 2: Register the machine

On any Linux machine (x64 or arm64), the Linux command downloads a pinned release of GitHub's
runner, checks its SHA-256, registers it and starts it as a service under the user `ews-runner`:

```sh
curl -fsSL https://console-host/ci/api/runners/install-linux.sh | sudo bash -s -- \
  --url https://git-host/organization --token token --labels gpu
```

Add `--ephemeral` for a machine that takes one job and is then retired, `--name` to name it, and
`--uninstall` to remove it again. A URL that ends in a repository (`…/organization/my-repo`)
comes with a token for that repository.

On any system GitHub's runner supports, register it by hand, as with GitHub, with the
`configCommand` of the token:

```sh
./config.sh --url https://git-host/organization --token token --disableupdate
./run.sh
```

## Result

The runner appears under **Runners** with its labels, group and status, and starts taking jobs its
labels and group allow. In GitHub-syntax workflows, send a job to it with `runs-on: self-hosted` or
`runs-on: [self-hosted, linux, gpu]` (see [Runners and runner groups](runners-and-groups.md)).

Registration is refused when the machine claims a label of another operating system ("A Linux
machine cannot carry the label macos: it would be sent macOS jobs."). Registering by hand with a
name another runner of the same organization or repository has is refused with "A runner with
that name is already registered here" unless you add `--replace`; the Linux command always
replaces a runner of the same name.

## Related

- [Connect a Mac](connect-a-mac.md)
- [Move or disable a runner](move-or-disable-a-runner.md)
- `ci.runners.create-registration-token` · `dcloud ci runners create-registration-token`
