Generate runner tokens
all tiers

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 available for all runners.

note
The token only displays in the UI for a short period of time during registration.

For a shared runner

Version history
On self-managed GitLab, by default this feature is available. To hide the feature, ask an administrator to disable the feature flag named create_runner_workflow_for_admin.

Prerequisites:

  • You must be an administrator.

To generate an authentication token for a shared runner:

  1. On the left sidebar, expand the top-most chevron ().
  2. Select Admin Area.
  3. On the left sidebar, select CI/CD > Runners.
  4. Select New instance runner.
  5. Select a platform.
  6. Optional. Enter configurations for the runner.
  7. Select Submit.
  8. Follow the instructions to register the runner from the command line.

You can also create a runner with the API to generate an authentication token.

For a group runner

Version history
On self-managed GitLab, by default this feature is available. To hide the feature, ask an administrator to disable the feature flag named create_runner_workflow_for_namespace.

Prerequisites:

  • You must have the Owner role for the group.

To generate an authentication token for a group runner:

  1. On the left sidebar, at the top, select Search GitLab () to find your group.
  2. Select Build > Runners.
  3. Select New group runner.
  4. Select a platform.
  5. Optional. Enter configurations for the runner.
  6. Select Submit.
  7. Follow the instructions to register the runner from the command line.

You can also create a runner with the API to generate an authentication token.

For a project runner

Version history
On self-managed GitLab, by default this feature is available. To hide the feature, ask an administrator to disable the feature flag named create_runner_workflow_for_namespace.

Prerequisites:

  • You must have the Maintainer role for the project.

To generate an authentication token for a project runner:

  1. On the left sidebar, at the top, select Search GitLab () to find your project.
  2. Select Settings > CI/CD.
  3. Expand the Runners section.
  4. Select New project runner.
  5. Select a platform.
  6. Optional. Enter configurations for the runner.
  7. Select Submit.
  8. Follow the instructions to register the runner from the command line.

You can also create a runner with the API to generate an authentication token.

Generate a registration token (deprecated)

caution
The ability to pass a runner registration token, and support for certain configuration arguments was deprecated in GitLab 15.6. Authentication tokens should be used instead to register runners. Registration tokens, and support for certain configuration arguments, will be removed in GitLab 17.0. For more information, see Migrating to the new runner registration workflow. The configuration arguments disabled for glrt- tokens will be --locked, --access-level, --run-untagged, --maximum-timeout, --paused, --tag-list, and --maintenance-note. This change is a breaking change.

For a shared runner

  1. On the left sidebar, expand the top-most chevron ().
  2. Select Admin Area.
  3. Select CI/CD > Runners.
  4. Select Register an instance runner.
  5. Copy the registration token.

For a group runner

  1. On the left sidebar, at the top, select Search GitLab () to find your group.
  2. Select Build > Runners.
  3. Copy the registration token.

For a project runner

  1. On the left sidebar, at the top, select Search GitLab () to find your project.
  2. Select Settings > CI/CD.
  3. Expand the Runners section.
  4. Copy the registration token.