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.

Last updated 18 November 2026View as Markdown

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.

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).
  • A machine with outbound HTTPS to the console and to your organization's Git host.

Step 1: Issue a registration token

  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.

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:

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:

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

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.

Did this page help you?