Registering runners

Tier: Free, Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

History

Runner registration is the process that links the runner with one or more GitLab instances. You must register the runner so that it can pick up jobs from the GitLab instance.

Requirements

Before you register a runner:

Install GitLab Runner on a server separate to where GitLab is installed.
For runner registration with Docker, install GitLab Runner in a Docker container.

Register with a runner authentication token

History

Prerequisites:

Obtain a runner authentication token. You can either:
- Create an instance, group, or project runner.
- Locate the runner authentication token in the config.toml file. Runner authentication tokens have the prefix, glrt-.

After you register the runner, the configuration is saved to the config.toml.

To register the runner with a runner authentication token:

Run the register command:
sudo gitlab-runner register
If you are behind a proxy, add an environment variable and then run the registration command:
export HTTP_PROXY=http://yourproxyurl:3128 export HTTPS_PROXY=http://yourproxyurl:3128 sudo -E gitlab-runner register
gitlab-runner register
.\gitlab-runner.exe register
sudo -u gitlab-runner -H /usr/local/bin/gitlab-runner register
To register with a container, you can either:
- Use a short-lived gitlab-runner container with the correct configuration volume mount:
  For local system volume mounts:
  docker run --rm -it -v /srv/gitlab-runner/config:/etc/gitlab-runner gitlab/gitlab-runner register
  If you used a configuration volume other than /srv/gitlab-runner/config during installation, update the command with the correct volume.
  For Docker volume mounts:
  docker run --rm -it -v gitlab-runner-config:/etc/gitlab-runner gitlab/gitlab-runner:latest register
- Use the executable inside an active runner container:
  docker exec -it gitlab-runner gitlab-runner register
Enter your GitLab URL:
- For runners on GitLab Self-Managed, use the URL for your GitLab instance. For example, if your project is hosted on gitlab.example.com/yourname/yourproject, your GitLab instance URL is https://gitlab.example.com.
- For runners on GitLab.com, the GitLab instance URL is https://gitlab.com.
Enter the runner authentication token.
Enter a description for the runner.
Enter the job tags, separated by commas.
Enter an optional maintenance note for the runner.
Enter the type of executor.

To register multiple runners on the same host machine, each with a different configuration, repeat the register command.
To register the same configuration on multiple host machines, use the same runner authentication token for each runner registration. For more information, see Reusing a runner configuration.

You can also use the non-interactive mode to use additional arguments to register the runner:

sudo gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --token "$RUNNER_TOKEN" \
  --executor "docker" \
  --docker-image alpine:latest \
  --description "docker-runner"

gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --token "$RUNNER_TOKEN" \
  --executor "docker" \
  --docker-image alpine:latest \
  --description "docker-runner"

.\gitlab-runner.exe register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --token "$RUNNER_TOKEN" \
  --executor "docker-windows" \
  --docker-image mcr.microsoft.com/windows/servercore:1809_amd64 \
  --description "docker-runner"

sudo -u gitlab-runner -H /usr/local/bin/gitlab-runner register
  --non-interactive \
  --url "https://gitlab.com/" \
  --token "$RUNNER_TOKEN" \
  --executor "docker" \
  --docker-image alpine:latest \
  --description "docker-runner"

docker run --rm -v /srv/gitlab-runner/config:/etc/gitlab-runner gitlab/gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --token "$RUNNER_TOKEN" \
  --executor "docker" \
  --docker-image alpine:latest \
  --description "docker-runner"

Register with a runner registration token (deprecated)

The ability to pass a runner registration token and support for certain configuration arguments was deprecated in GitLab 15.6. They are scheduled for removal in GitLab 18.0. Use runner authentication tokens instead. For more information, see Migrating to the new runner registration workflow.

Prerequisites:

Runner registration tokens must be enabled in the Admin Area.
Obtain a runner registration token at the desired instance, group, or project.

After you register the runner, the configuration is saved to the config.toml.

To register the runner with a runner registration token:

Run the register command:

sudo gitlab-runner register

If you are behind a proxy, add an environment variable and then run the registration command:

export HTTP_PROXY=http://yourproxyurl:3128
export HTTPS_PROXY=http://yourproxyurl:3128

sudo -E gitlab-runner register

gitlab-runner register

.\gitlab-runner.exe register

sudo -u gitlab-runner -H /usr/local/bin/gitlab-runner register

To launch a short-lived gitlab-runner container to register the container you created during installation:

For local system volume mounts:
```
docker run --rm -it -v /srv/gitlab-runner/config:/etc/gitlab-runner gitlab/gitlab-runner register
```
If you used a configuration volume other than /srv/gitlab-runner/config during installation, update the command with the correct volume.

For Docker volume mounts:

docker run --rm -it -v gitlab-runner-config:/etc/gitlab-runner gitlab/gitlab-runner:latest register

Enter your GitLab URL:
- For runners on GitLab Self-Managed, use the URL for your GitLab instance. For example, if your project is hosted on gitlab.example.com/yourname/yourproject, your GitLab instance URL is https://gitlab.example.com.
- For GitLab.com, the GitLab instance URL is https://gitlab.com.
Enter the token you obtained to register the runner.
Enter a description for the runner.
Enter the job tags, separated by commas.
Enter an optional maintenance note for the runner.
Enter the type of executor.

To register multiple runners on the same host machine, each with a different configuration, repeat the register command.

You can also use the non-interactive mode to use additional arguments to register the runner:

sudo gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --registration-token "$PROJECT_REGISTRATION_TOKEN" \
  --executor "docker" \
  --docker-image alpine:latest \
  --description "docker-runner" \
  --maintenance-note "Free-form maintainer notes about this runner" \
  --tag-list "docker,aws" \
  --run-untagged="true" \
  --locked="false" \
  --access-level="not_protected"

gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --registration-token "$PROJECT_REGISTRATION_TOKEN" \
  --executor "docker" \
  --docker-image alpine:latest \
  --description "docker-runner" \
  --maintenance-note "Free-form maintainer notes about this runner" \
  --tag-list "docker,aws" \
  --run-untagged="true" \
  --locked="false" \
  --access-level="not_protected"

.\gitlab-runner.exe register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --registration-token "$PROJECT_REGISTRATION_TOKEN" \
  --executor "docker-windows" \
  --docker-image mcr.microsoft.com/windows/servercore:1809_amd64 \
  --description "docker-runner" \
  --maintenance-note "Free-form maintainer notes about this runner" \
  --tag-list "docker,aws" \
  --run-untagged="true" \
  --locked="false" \
  --access-level="not_protected"

sudo -u gitlab-runner -H /usr/local/bin/gitlab-runner register
  --non-interactive \
  --url "https://gitlab.com/" \
  --registration-token "$PROJECT_REGISTRATION_TOKEN" \
  --executor "docker" \
  --docker-image alpine:latest \
  --description "docker-runner" \
  --maintenance-note "Free-form maintainer notes about this runner" \
  --tag-list "docker,aws" \
  --run-untagged="true" \
  --locked="false" \
  --access-level="not_protected"

docker run --rm -v /srv/gitlab-runner/config:/etc/gitlab-runner gitlab/gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --registration-token "$PROJECT_REGISTRATION_TOKEN" \
  --executor "docker" \
  --docker-image alpine:latest \
  --description "docker-runner" \
  --maintenance-note "Free-form maintainer notes about this runner" \
  --tag-list "docker,aws" \
  --run-untagged="true" \
  --locked="false" \
  --access-level="not_protected"

--access-level creates a protected runner.
- For a protected runner, use the --access-level="ref_protected" parameter.
- For an unprotected runner, use --access-level="not_protected" or leave the value undefined.
--maintenance-note allows adding information you might find helpful for runner maintenance. The maximum length is 255 characters.

Legacy-compatible registration process

History

Runner registration tokens and several runner configuration arguments were deprecated in GitLab 15.6. They are scheduled for removal in GitLab 18.0. To ensure minimal disruption to your automation workflow, the legacy-compatible registration process triggers if a runner authentication token is specified in the legacy parameter --registration-token.

The legacy-compatible registration process ignores the following command-line parameters. These parameters can only be configured when a runner is created in the UI or with the API.

--locked
--access-level
--run-untagged
--maximum-timeout
--paused
--tag-list
--maintenance-note

Register with a configuration template

You can use a configuration template to register a runner with settings that are not supported by the register command.

Prerequisites:

The volume for the location of the template file must be mounted on the GitLab Runner container.
A runner authentication or registration token:
- Obtain a runner authentication token (recommended). You can either:
  - Create an instance, group, or project runner.
  - Locate the runner authentication token in the config.toml file. Runner authentication tokens have the prefix, glrt-.
- Obtain a runner registration token (deprecated) for an instance, group, or project runner.

The configuration template can be used for automated environments that do not support some arguments in the register command due to:

Size limits on environment variables based on the environment.
Command-line options that are not available for executor volumes for Kubernetes.

The configuration template supports only a single [[runners]] section and does not support global options.

To register a runner:

Create a configuration template file with the .toml format and add your specifications. For example:

[[runners]]
  [runners.kubernetes]
  [runners.kubernetes.volumes]
    [[runners.kubernetes.volumes.empty_dir]]
      name = "empty_dir"
      mount_path = "/path/to/empty_dir"
      medium = "Memory"

Add the path to the file. You can use either:

The non-interactive mode in the command line:

$ sudo gitlab-runner register \
    --template-config /tmp/test-config.template.toml \
    --non-interactive \
    --url "https://gitlab.com" \
    --token <TOKEN> \ "# --registration-token if using the deprecated runner registration token"
    --name test-runner \
    --executor kubernetes
    --host = "http://localhost:9876/"

The environment variable in the .gitlab.yaml file:
```
variables:
  TEMPLATE_CONFIG_FILE = <file_path>
```
If you update the environment variable, you do not need to add the file path in the register command each time you register.

After you register the runner, the settings in the configuration template are merged with the [[runners]] entry created in the config.toml:

concurrent = 1
check_interval = 0

[session_server]
  session_timeout = 1800

[[runners]]
  name = "test-runner"
  url = "https://gitlab.com"
  token = "glrt-<TOKEN>"
  executor = "kubernetes"
  [runners.kubernetes]
    host = "http://localhost:9876/"
    bearer_token_overwrite_allowed = false
    image = ""
    namespace = ""
    namespace_overwrite_allowed = ""
    privileged = false
    service_account_overwrite_allowed = ""
    pod_labels_overwrite_allowed = ""
    pod_annotations_overwrite_allowed = ""
    [runners.kubernetes.volumes]

      [[runners.kubernetes.volumes.empty_dir]]
        name = "empty_dir"
        mount_path = "/path/to/empty_dir"
        medium = "Memory"

Template settings are merged only for options that are:

Empty strings
Null or non-existent entries
Zeroes

Command-line arguments or environment variables take precedence over settings in the configuration template. For example, if the template specifies a docker executor, but the command line specifies shell, the configured executor is shell.

Register a runner for GitLab Community Edition integration tests

To test GitLab Community Edition integrations, use a configuration template to register a runner with a confined Docker executor.

Create a project runner.

Create a template with the [[runners.docker.services]] section:

$ cat > /tmp/test-config.template.toml << EOF
[[runners]]
[runners.docker]
[[runners.docker.services]]
name = "mysql:latest"
[[runners.docker.services]]
name = "redis:latest"

EOF

sudo gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com" \
  --token "$RUNNER_AUTHENTICATION_TOKEN" \
  --template-config /tmp/test-config.template.toml \
  --description "gitlab-ce-ruby-2.7" \
  --executor "docker" \
  --docker-image ruby:2.7

gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com" \
  --token "$RUNNER_AUTHENTICATION_TOKEN" \
  --template-config /tmp/test-config.template.toml \
  --description "gitlab-ce-ruby-2.7" \
  --executor "docker" \
  --docker-image ruby:2.7

.\gitlab-runner.exe register \
  --non-interactive \
  --url "https://gitlab.com" \
  --token "$RUNNER_AUTHENTICATION_TOKEN" \
  --template-config /tmp/test-config.template.toml \
  --description "gitlab-ce-ruby-2.7" \
  --executor "docker" \
  --docker-image ruby:2.7

sudo -u gitlab-runner -H /usr/local/bin/gitlab-runner register
  --non-interactive \
  --url "https://gitlab.com" \
  --token "$RUNNER_AUTHENTICATION_TOKEN" \
  --template-config /tmp/test-config.template.toml \
  --description "gitlab-ce-ruby-2.7" \
  --executor "docker" \
  --docker-image ruby:2.7

docker run --rm -v /srv/gitlab-runner/config:/etc/gitlab-runner gitlab/gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com" \
  --token "$RUNNER_AUTHENTICATION_TOKEN" \
  --template-config /tmp/test-config.template.toml \
  --description "gitlab-ce-ruby-2.7" \
  --executor "docker" \
  --docker-image ruby:2.7

For more configuration options, see Advanced configuration.

Registering runners with Docker

After you register the runner with a Docker container:

The configuration is written to your configuration volume. For example, /srv/gitlab-runner/config.
The container uses the configuration volume to load the runner.

If gitlab-runner restart runs in a Docker container, GitLab Runner starts a new process instead of restarting the existing process. To apply configuration changes, restart the Docker container instead.

Troubleshooting

`Check registration token` error

The check registration token error message displays when the GitLab instance does not recognize the runner registration token entered during registration. This issue can occur when either:

The instance, group, or project runner registration token was changed in GitLab.
An incorrect runner registration token was entered.

When this error occurs, you can ask a GitLab administrator to:

Verify that the runner registration token is valid.
Confirm that runner registration in the project or group is permitted.

`410 Gone - runner registration disallowed` error

The 410 Gone - runner registration disallowed error message displays when runner registration through registration tokens has been disabled.

When this error occurs, you can ask a GitLab administrator to:

Verify that the runner registration token is valid.
Confirm that runner registration in the instance is permitted.
In the case of a group or project runner registration token, verify that runner registration in the respective group and/or project is allowed.

Docs

Edit this page to fix an error or add an improvement in a merge request.

Create an issue to suggest an improvement to this page.

Product

Create an issue if there's something you don't like about this feature.

Propose functionality by submitting a feature request.

Feature availability and product trials

View pricing to see all GitLab tiers and features, or to upgrade.

Try GitLab for free with access to all features for 30 days.

Get help

If you didn't find what you were looking for, search the docs.

If you want help with something specific and could use community support, post on the GitLab forum.

For problems setting up or using this feature (depending on your GitLab subscription).

Request support

Registering runners

Requirements

Register with a runner authentication token

Register with a runner registration token (deprecated)

Legacy-compatible registration process

Register with a configuration template

Register a runner for GitLab Community Edition integration tests

Registering runners with Docker

Troubleshooting

Check registration token error

410 Gone - runner registration disallowed error

Help & feedback

Docs

Product

Feature availability and product trials

Get help

`Check registration token` error

`410 Gone - runner registration disallowed` error