Generate runner tokens

To register a runner, you can use either:

  • An authentication token assigned to the runner when you create the runner in the UI. The runner uses the token to authenticate with GitLab when picking up jobs from the job queue.
  • A registration token (deprecated).

Generate an authentication token

Registration with an authentication token is only available for shared runners. Support for project and group runners is proposed in this epic.

For a shared runner

Introduced in GitLab 15.10. Deployed behind the create_runner_workflow_for_admin flag, disabled by default.

On self-managed GitLab, this feature is not available. To make it available, ask an administrator to enable the feature flag named create_runner_workflow_for_admin. On GitLab.com, this feature is available but can be configured by GitLab.com administrators only.

Prerequisites:

  • You must be an administrator.

To generate an authentication token for a shared runner:

  1. On the top bar, select Main menu > Admin.
  2. On the left sidebar, select CI/CD > Runners.
  3. Select New instance runner.
  4. Select a platform.
  5. Optional. Enter a description.
  6. Optional. Enter a maintenance note.
  7. Optional. Enter configurations for the runner.
  8. Select Submit.
  9. Follow the instructions to register the runner from the command line.
note
The token only displays in the UI for a short period of time during registration, and is then saved in config.toml.

Generate a registration token (deprecated)

caution
The ability to pass a runner registration token was deprecated in GitLab 15.6 and is planned for removal in 17.0, along with support for certain configuration arguments. This change is a breaking change. GitLab plans to introduce a new GitLab Runner token architecture, which introduces a new method for registering runners and eliminates the legacy runner registration token.

For a shared runner

  1. On the top bar, select Main menu > Admin.
  2. On the left sidebar, select CI/CD > Runners.
  3. Select Register an instance runner.
  4. Copy the registration token.

For a group runner

  1. On the top bar, select Main menu > Groups and find your group.
  2. On the left sidebar, select CI/CD > Runners.
  3. Copy the registration token.

For a project runner

  1. On the top bar, select Main menu > Projects and find your project.
  2. On the left sidebar, select Settings > CI/CD.
  3. Expand the Runners section.
  4. Copy the registration token.