- Requirements
- Register with a runner authentication token
- Register with a runner registration token (deprecated)
- Register with a configuration template
- Register a runner for GitLab Community Edition integration tests
- Registering runners with Docker
- Troubleshooting
Registering runners
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
Prerequisites:
- Obtain a runner authentication token. You can either:
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:
Linuxsudo 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
macOSgitlab-runner register
Windows.\gitlab-runner.exe register
FreeBSDsudo -u gitlab-runner -H /usr/local/bin/gitlab-runner register
DockerTo register with a container, you can either:
-
Use a short-lived
gitlab-runner
container with the correct config 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 ishttps://gitlab.example.com
. - For runners on GitLab.com, the GitLab instance URL is
https://gitlab.com
.
- For runners on GitLab self-managed, use the URL for your GitLab instance. For example,
if your project is hosted on
- 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 "/proxy/https://docs.gitlab.com/?__proxy_cookies_to=https%3A%2F%2Fgitlab.com%2F" \
--token "$RUNNER_TOKEN" \
--executor "docker" \
--docker-image alpine:latest \
--description "docker-runner"
gitlab-runner register \
--non-interactive \
--url "/proxy/https://docs.gitlab.com/?__proxy_cookies_to=https%3A%2F%2Fgitlab.com%2F" \
--token "$RUNNER_TOKEN" \
--executor "docker" \
--docker-image alpine:latest \
--description "docker-runner"
.\gitlab-runner.exe register \
--non-interactive \
--url "/proxy/https://docs.gitlab.com/?__proxy_cookies_to=https%3A%2F%2Fgitlab.com%2F" \
--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 "/proxy/https://docs.gitlab.com/?__proxy_cookies_to=https%3A%2F%2Fgitlab.com%2F" \
--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 "/proxy/https://docs.gitlab.com/?__proxy_cookies_to=https%3A%2F%2Fgitlab.com%2F" \
--token "$RUNNER_TOKEN" \
--executor "docker" \
--docker-image alpine:latest \
--description "docker-runner"
Register with a runner registration token (deprecated)
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:
Linuxsudo 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
macOSgitlab-runner register
Windows.\gitlab-runner.exe register
FreeBSDsudo -u gitlab-runner -H /usr/local/bin/gitlab-runner register
DockerTo 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 GitLab self-managed runners, use the URL for your GitLab instance. For example,
if your project is hosted on
gitlab.example.com/yourname/yourproject
, your GitLab instance URL ishttps://gitlab.example.com
. - For GitLab.com, the GitLab instance URL is
https://gitlab.com
.
- For GitLab self-managed runners, use the URL for your GitLab instance. For example,
if your project is hosted on
- 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 "/proxy/https://docs.gitlab.com/?__proxy_cookies_to=https%3A%2F%2Fgitlab.com%2F" \
--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 "/proxy/https://docs.gitlab.com/?__proxy_cookies_to=https%3A%2F%2Fgitlab.com%2F" \
--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 "/proxy/https://docs.gitlab.com/?__proxy_cookies_to=https%3A%2F%2Fgitlab.com%2F" \
--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 "/proxy/https://docs.gitlab.com/?__proxy_cookies_to=https%3A%2F%2Fgitlab.com%2F" \
--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 "/proxy/https://docs.gitlab.com/?__proxy_cookies_to=https%3A%2F%2Fgitlab.com%2F" \
--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.
- For a protected runner, use the
-
--maintenance-note
allows adding information you might find helpful for runner maintenance. The maximum length is 255 characters.
Legacy-compatible registration process
Runner registration tokens and several runner configuration arguments were legacy-compatible registration process triggers
if a runner authentication token is specified in the legacy parameter 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.
You can use a configuration template to register a runner with settings that are not supported by the Prerequisites:
The configuration template can be used for automated environments that do not support some arguments
in the To register a runner:
Create a configuration template file with the Add the path to the file. You can use either:
The non-interactive mode in the command line:
The environment variable in the If you update the environment variable, you do not need to
add the file path in the After you register the runner, the settings in the configuration template
are merged with the Template settings are merged only for options that are:
Command-line arguments or environment variables take precedence over
settings in the configuration template. For example, if the template
specifies a To test GitLab Community Edition integrations, use a configuration template to register a runner
with a confined Docker executor.
Create a template with the Register the runner:
For more configuration options, see Advanced configuration.
After you register the runner with a Docker container:
The When this error occurs, you can ask a GitLab administrator to:
The When this error occurs, you can ask a GitLab administrator to:
--registration-token
.
--locked
--access-level
--run-untagged
--maximum-timeout
--paused
--tag-list
--maintenance-note
Register with a configuration template
register
command.
register
command due to:
[[runners]]
section and does not support global options.
.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"
$ sudo gitlab-runner register \
--template-config /tmp/test-config.template.toml \
--non-interactive \
--url "/proxy/https://docs.gitlab.com/?__proxy_cookies_to=https%3A%2F%2Fgitlab.com" \
--token <TOKEN> \ "# --registration-token if using the deprecated runner registration token"
--name test-runner \
--executor kubernetes
--host = "/proxy/http://localhost:9876/"
.gitlab.yaml
file:
variables:
TEMPLATE_CONFIG_FILE = <file_path>
register
command each time you register.
[[runners]]
entry created in the config.toml
:
concurrent = 1
check_interval = 0
[session_server]
session_timeout = 1800
[[runners]]
name = "test-runner"
url = "/proxy/https://docs.gitlab.com/?__proxy_cookies_to=https%3A%2F%2Fgitlab.com"
token = "glrt-<TOKEN>"
executor = "kubernetes"
[runners.kubernetes]
host = "/proxy/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"
docker
executor, but the command line specifies shell
,
the configured executor is shell
.
Register a runner for GitLab Community Edition integration tests
[[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 "/proxy/https://docs.gitlab.com/?__proxy_cookies_to=https%3A%2F%2Fgitlab.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 "/proxy/https://docs.gitlab.com/?__proxy_cookies_to=https%3A%2F%2Fgitlab.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 "/proxy/https://docs.gitlab.com/?__proxy_cookies_to=https%3A%2F%2Fgitlab.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 "/proxy/https://docs.gitlab.com/?__proxy_cookies_to=https%3A%2F%2Fgitlab.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 "/proxy/https://docs.gitlab.com/?__proxy_cookies_to=https%3A%2F%2Fgitlab.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
Registering runners with Docker
/srv/gitlab-runner/config
.
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
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:
410 Gone - runner registration disallowed
error
410 Gone - runner registration disallowed
error message displays when runner registration through
registration tokens has been disabled.