doc/ci/runners/new_creation_workflow.md
{{< details >}}
{{< /details >}}
[!disclaimer]
GitLab 16.0 introduced a new runner creation workflow that uses runner authentication tokens to register runners. The legacy workflow that uses registration tokens is not recommended. Use the runner creation workflow instead.
For information about the current development status of the new workflow, see epic 7663.
For information about the technical design and reasons for the new architecture, see next GitLab Runner Token architecture.
If you experience problems or have concerns about the new runner registration workflow, or need more information, let us know in the feedback issue.
For the new runner registration workflow, you:
The new runner registration workflow has the following benefits:
In GitLab 16.11 and earlier, you can use the legacy runner registration workflow.
In GitLab 17.0 and later, the legacy runner registration workflow can be disabled by instance administrators or group owners. For more information, see Using registration tokens after GitLab 17.0.
If you register a runner without migrating to the new workflow, the runner registration breaks and the gitlab-runner register command returns a 410 Gone - runner registration disallowed error.
To avoid a broken workflow, you must:
To continue using registration tokens after GitLab 17.0:
Existing runners will continue to work as usual after upgrading to GitLab 17.0. This change only affects registration of new runners.
The GitLab Runner Helm chart generates new runner pods every time a job is executed. For these runners, enable legacy runner registration to use registration tokens.
gitlab-runner register command syntaxThe gitlab-runner register command accepts runner authentication tokens instead of registration tokens.
You can generate tokens from the Runners page in the Admin area.
The runner authentication tokens are recognizable by their glrt- prefix.
When you create a runner in the GitLab UI, you specify configuration values that were previously command-line options
prompted by the gitlab-runner register command.
If you specify a runner authentication token with:
--token command-line option, the gitlab-runner register command does not accept the configuration values.--registration-token command-line option, the gitlab-runner register command ignores the configuration values.| Token | Registration command |
|---|---|
| Runner authentication token | gitlab-runner register --token $RUNNER_AUTHENTICATION_TOKEN |
| Runner registration token (legacy) | gitlab-runner register --registration-token $RUNNER_REGISTRATION_TOKEN <runner configuration arguments> |
Authentication tokens have the prefix, glrt-.
To ensure minimal disruption to your automation workflow,
legacy-compatible registration processing
triggers if a runner authentication token is specified in the legacy parameter --registration-token.
Example command for GitLab 15.9:
gitlab-runner register \
--non-interactive \
--executor "shell" \
--url "https://gitlab.com/" \
--tag-list "shell,mac,gdk,test" \
--run-untagged "false" \
--locked "false" \
--access-level "not_protected" \
--registration-token "REDACTED"
In GitLab 15.10 and later, you can create the runner and set attributes in the UI, like
tag list, locked status, and access level.
In GitLab 15.11 and later, these attributes are no longer accepted as arguments to register when a runner authentication token with the glrt- prefix is specified.
The following example shows the new command:
gitlab-runner register \
--non-interactive \
--executor "shell" \
--url "https://gitlab.com/" \
--token "REDACTED"
In autoscaling scenarios such as GitLab Runner Operator or GitLab Runner Helm Chart, the runner authentication token generated from the UI replaces the registration token. This means that the same runner configuration is reused across jobs, instead of creating a runner for each job. The specific runner can be identified by the unique system ID that is generated when the runner process is started.
In GitLab 15.11 and later, you can use the POST /user/runners REST API to create a runner as an authenticated user. This should only be used if the runner configuration is dynamic or not reusable. If the runner configuration is static, you should reuse the runner authentication token of an existing runner.
For instructions about how to automate runner creation and registration, see the tutorial, Automate runner creation and registration.
Several runner configuration options cannot be set during runner registration if runner registration tokens are disabled. These options can only be configured:
user/runners REST API endpoint.The following configuration options are not supported in values.yaml in that scenario:
## If a runner authentication token is specified in runnerRegistrationToken, the registration will succeed, however the
## other values will be ignored.
runnerRegistrationToken: ""
locked: true
tags: ""
maximumTimeout: ""
runUntagged: true
protected: true
For GitLab Runner on Kubernetes, Helm deploy passes the runner authentication token to the runner worker pod and creates the runner configuration.
In GitLab 17.0 and later, if you use the runnerRegistrationToken token field on Kubernetes hosted runners attached to GitLab.com, the runner worker pod tries to use the legacy Registration API method during creation.
Replace the invalid runnerRegistrationToken field with the runnerToken field. You must also modify the runner authentication token stored in secrets.
In the legacy runner registration workflow, fields were specified with:
apiVersion: v1
kind: Secret
metadata:
name: gitlab-runner-secret
type: Opaque
data:
runner-registration-token: "REDACTED" # DEPRECATED, set to ""
runner-token: ""
In the new runner registration workflow, you must use runner-token instead:
apiVersion: v1
kind: Secret
metadata:
name: gitlab-runner-secret
type: Opaque
data:
runner-registration-token: "" # need to leave as an empty string for compatibility reasons
runner-token: "REDACTED"
[!note] If your secret management solution doesn't allow you to set an empty string for
runner-registration-token, you can set it to any string. This value is ignored whenrunner-tokenis present.
When you use the new registration workflow to register your runners with Helm chart, the pod name doesn't appear on the runner details page. For more information, see issue 423523.
When you register runners on multiple host machines through the new workflow with automatic token rotation, only the first runner manager receives the new token. The remaining runner managers continue to use the invalid token and become disconnected. You must update these managers manually to use the new token.
During runner registration with GitLab Operator through the new workflow, the runner authentication token in the Custom Resource Definition doesn't update during token rotation. This occurs when:
glrt-) in a secret
referenced by a Custom Resource Definition.For more information, see issue 186.