- Requirements
- GNU/Linux
- macOS
- Windows
- FreeBSD
- Docker
- One-line registration command
-
[[runners]]
configuration template file
Registering Runners
Registering a Runner is the process that binds the Runner with a GitLab instance.
Requirements
Before registering a Runner, you need to first:
- Install it on a server separate than where GitLab is installed on
- Obtain a token for a shared or specific Runner via GitLab’s interface
GNU/Linux
To register a Runner under GNU/Linux:
-
Run the following command:
sudo gitlab-runner register
-
Enter your GitLab instance URL:
Please enter the gitlab-ci coordinator URL (e.g. https://gitlab.com ) https://gitlab.com
-
Enter the token you obtained to register the Runner:
Please enter the gitlab-ci token for this runner xxx
-
Enter a description for the Runner, you can change this later in GitLab’s UI:
Please enter the gitlab-ci description for this runner [hostname] my-runner
-
Enter the tags associated with the Runner, you can change this later in GitLab’s UI:
Please enter the gitlab-ci tags for this runner (comma separated): my-tag,another-tag
-
Enter the Runner executor:
Please enter the executor: ssh, docker+machine, docker-ssh+machine, kubernetes, docker, parallels, virtualbox, docker-ssh, shell: docker
-
If you chose Docker as your executor, you’ll be asked for the default image to be used for projects that do not define one in
.gitlab-ci.yml
:Please enter the Docker image (eg. ruby:2.6): alpine:latest
macOS
To register a Runner under macOS:
-
Run the following command:
gitlab-runner register
-
Enter your GitLab instance URL:
Please enter the gitlab-ci coordinator URL (e.g. https://gitlab.com ) https://gitlab.com
-
Enter the token you obtained to register the Runner:
Please enter the gitlab-ci token for this runner xxx
-
Enter a description for the Runner, you can change this later in GitLab’s UI:
Please enter the gitlab-ci description for this runner [hostname] my-runner
-
Enter the tags associated with the Runner, you can change this later in GitLab’s UI:
Please enter the gitlab-ci tags for this runner (comma separated): my-tag,another-tag
-
Enter the Runner executor:
Please enter the executor: ssh, docker+machine, docker-ssh+machine, kubernetes, docker, parallels, virtualbox, docker-ssh, shell: docker
-
If you chose Docker as your executor, you’ll be asked for the default image to be used for projects that do not define one in
.gitlab-ci.yml
:Please enter the Docker image (eg. ruby:2.6): alpine:latest
Windows
To register a Runner under Windows:
-
Run the following command:
./gitlab-runner.exe register
-
Enter your GitLab instance URL:
Please enter the gitlab-ci coordinator URL (e.g. https://gitlab.com ) https://gitlab.com
-
Enter the token you obtained to register the Runner:
Please enter the gitlab-ci token for this runner xxx
-
Enter a description for the Runner, you can change this later in GitLab’s UI:
Please enter the gitlab-ci description for this runner [hostname] my-runner
-
Enter the tags associated with the Runner, you can change this later in GitLab’s UI:
Please enter the gitlab-ci tags for this runner (comma separated): my-tag,another-tag
-
Enter the Runner executor:
Please enter the executor: ssh, docker+machine, docker-ssh+machine, kubernetes, docker, parallels, virtualbox, docker-ssh, shell: docker
-
If you chose Docker as your executor, you’ll be asked for the default image to be used for projects that do not define one in
.gitlab-ci.yml
:Please enter the Docker image (eg. ruby:2.6): alpine:latest
If you’d like to register multiple Runners on the same machine with different
configurations repeat the ./gitlab-runner.exe register
command.
FreeBSD
To register a Runner under FreeBSD:
-
Run the following command:
sudo -u gitlab-runner -H /usr/local/bin/gitlab-runner register
-
Enter your GitLab instance URL:
Please enter the gitlab-ci coordinator URL (e.g. https://gitlab.com ) https://gitlab.com
-
Enter the token you obtained to register the Runner:
Please enter the gitlab-ci token for this runner xxx
-
Enter a description for the Runner, you can change this later in GitLab’s UI:
Please enter the gitlab-ci description for this runner [hostname] my-runner
-
Enter the tags associated with the Runner, you can change this later in GitLab’s UI:
Please enter the gitlab-ci tags for this runner (comma separated): my-tag,another-tag
-
Enter the Runner executor:
Please enter the executor: ssh, docker+machine, docker-ssh+machine, kubernetes, docker, parallels, virtualbox, docker-ssh, shell: docker
-
If you chose Docker as your executor, you’ll be asked for the default image to be used for projects that do not define one in
.gitlab-ci.yml
:Please enter the Docker image (eg. ruby:2.6): alpine:latest
Docker
These instructions are meant to be followed after Run GitLab Runner in a container.
In this section, you will launch an ephemeral gitlab-runner
container to
register the container that you created during install. After you finish
registration, the resulting configuration will be written to your chosen config
volume (e.g. /srv/gitlab-runner/config
), and will be automatically loaded by
the runner using that config volume.
To register a Runner using a Docker container:
-
Run the register command:
docker run --rm -t -i -v /srv/gitlab-runner/config:/etc/gitlab-runner gitlab/gitlab-runner register
Note: If you used a config volume other than/srv/gitlab-runner/config
during install, then you should update the command with the correct volume. -
Enter your GitLab instance URL:
Please enter the gitlab-ci coordinator URL (e.g. https://gitlab.com ) https://gitlab.com
-
Enter the token you obtained to register the Runner:
Please enter the gitlab-ci token for this runner xxx
-
Enter a description for the Runner, you can change this later in GitLab’s UI:
Please enter the gitlab-ci description for this runner [hostname] my-runner
-
Enter the tags associated with the Runner, you can change this later in GitLab’s UI:
Please enter the gitlab-ci tags for this runner (comma separated): my-tag,another-tag
-
Enter the Runner executor:
Please enter the executor: ssh, docker+machine, docker-ssh+machine, kubernetes, docker, parallels, virtualbox, docker-ssh, shell: docker
-
If you chose Docker as your executor, you’ll be asked for the default image to be used for projects that do not define one in
.gitlab-ci.yml
:Please enter the Docker image (eg. ruby:2.6): alpine:latest
One-line registration command
If you want to use the non-interactive mode to register a Runner, you can
either use the register
subcommands or use their equivalent environment
variables.
To see a list of all the register
subcommands, use:
gitlab-runner register -h
To register a Runner using the most common options, you would do:
sudo gitlab-runner register \
--non-interactive \
--url "https://gitlab.com/" \
--registration-token "PROJECT_REGISTRATION_TOKEN" \
--executor "docker" \
--docker-image alpine:latest \
--description "docker-runner" \
--tag-list "docker,aws" \
--run-untagged="true" \
--locked="false" \
--access-level="not_protected"
If you’re running the Runner in a Docker container, the register
command would
look like:
docker run --rm -v /srv/gitlab-runner/config:/etc/gitlab-runner gitlab/gitlab-runner register \
--non-interactive \
--executor "docker" \
--docker-image alpine:latest \
--url "https://gitlab.com/" \
--registration-token "PROJECT_REGISTRATION_TOKEN" \
--description "docker-runner" \
--tag-list "docker,aws" \
--run-untagged="true" \
--locked="false" \
--access-level="not_protected"
[[runners]]
configuration template file
Introduced in GitLab Runner 12.2.
Some Runner configuration settings can’t be set with environment variables or command line options.
For example:
- Environment variables do not support slices.
- Command line option support is internationally unavailable for the settings for the whole Kubernetes executor volumes tree.
This is a problem for environments that are handled by any kind of automation, such as the
GitLab Runner official Helm chart. In cases like these, the only solution was
to manually update the config.toml
file after the Runner was registered. This is less
than ideal, error-prone, and not reliable. Especially when more than one registration
for the same Runner installation is done.
This problem can be resolved with the usage of a configuration template file.
To use a configuration template file, pass a path to the file to register
with either
the:
-
--template-config
command line option. -
TEMPLATE_CONFIG_FILE
environment variable.
The configuration template file supports:
- Only a single
[[runners]]
section. - No global options.
When --template-config
or TEMPLATE_CONFIG_FILE
is used, the configuration of [[runners]]
entry
is merged into the configuration of newly created [[runners]]
entry in the regular config.toml
file.
The merging is done only for options that were empty. That is:
- Empty strings.
- Nulls or/non existent entries.
- Zeroes.
With this:
- All configuration provided with command line options and/or environment variables during the
register
command call take precedence. - The template fills the gaps and adds additional settings.
Example
We register a Kubernetes-executor-based Runner to some test project and see what the
config.toml
file looks like:
$ sudo gitlab-runner register \
--config /tmp/test-config.toml \
--non-interactive \
--url https://gitlab.com \
--registration-token __REDACTED__ \
--name test-runner \
--tag-list kubernetes,test \
--locked \
--paused \
--executor kubernetes \
--kubernetes-host http://localhost:9876/
Runtime platform arch=amd64 os=linux pid=1684 revision=88310882 version=11.10.0~beta.1251.g88310882
Registering runner... succeeded runner=__REDACTED__
Runner registered successfully. Feel free to start it, but if it's running already the config should be automatically reloaded!
The command above will create the following config.toml
file:
concurrent = 1
check_interval = 0
[session_server]
session_timeout = 1800
[[runners]]
name = "test-runner"
url = "https://gitlab.com"
token = "__REDACTED__"
executor = "kubernetes"
[runners.cache]
[runners.cache.s3]
[runners.cache.gcs]
[runners.kubernetes]
host = "http://localhost:9876/"
bearer_token_overwrite_allowed = false
image = ""
namespace = ""
namespace_overwrite_allowed = ""
privileged = false
service_account_overwrite_allowed = ""
pod_annotations_overwrite_allowed = ""
[runners.kubernetes.volumes]
We can see the basic configuration created from the provided command line options:
- Runner credentials (URL and token).
- The executor specified.
- The default, empty section
runners.kubernetes
with only the one option provided during the registration filled out.
Normally one would need to set few more options to make the Kubernetes executor usable, but the above is enough for the purpose of our example.
Let’s now assume that we need to configure an emptyDir
volume for our Kubernetes executor. There is
no way to add this while registering with neither environment variables nor command line options.
We would need to manually append something like this to the end of the file:
[[runners.kubernetes.volumes.empty_dir]]
name = "empty_dir"
mount_path = "/path/to/empty_dir"
medium = "Memory"
Because TOML doesn’t require proper indentation (it
relies on entries ordering), we could just append the required changes to the end of the
file.
However, this becomes tricky when more [[runners]]
sections are being registered
within one config.toml
file. The assumption that the new one will be always at the
end is risky.
With GitLab Runner 12.2, this becomes much easier using the --template-config
flag.
$ cat > /tmp/test-config.template.toml << EOF
[[runners]]
[runners.kubernetes]
[runners.kubernetes.volumes]
[[runners.kubernetes.volumes.empty_dir]]
name = "empty_dir"
mount_path = "/path/to/empty_dir"
medium = "Memory"
EOF
Having the file, we can now try to register the Runner again, but this time adding the
--template-config /tmp/test-config.template.toml
option. Apart from this change, the
rest of registration command will be exactly the same:
$ sudo gitlab-runner register \
--config /tmp/test-config.toml \
--template-config /tmp/test-config.template.toml \
--non-interactive \
--url https://gitlab.com \
--registration-token __REDACTED__ \
--name test-runner \
--tag-list kubernetes,test \
--locked \
--paused \
--executor kubernetes \
--kubernetes-host http://localhost:9876/
Runtime platform arch=amd64 os=linux pid=8798 revision=88310882 version=11.10.0~beta.1251.g88310882
Registering runner... succeeded runner=__REDACTED__
Merging configuration from template file
Runner registered successfully. Feel free to start it, but if it's running already the config should be automatically reloaded!
As we can see, there is a little change in the output of the registration command.
We can see a Merging configuration from template file
line.
Now let’s see what the configuration file looks like after using the template:
concurrent = 1
check_interval = 0
[session_server]
session_timeout = 1800
[[runners]]
name = "test-runner"
url = "https://gitlab.com"
token = "__REDACTED__"
executor = "kubernetes"
[runners.cache]
[runners.cache.s3]
[runners.cache.gcs]
[runners.kubernetes]
host = "http://localhost:9876/"
bearer_token_overwrite_allowed = false
image = ""
namespace = ""
namespace_overwrite_allowed = ""
privileged = false
service_account_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"
We can see, that the configuration is almost the same as it was previously. The only
change is that it now has the [[runners.kubernetes.volumes.empty_dir]]
entry with
its options at the end of the file. It’s added to the [[runners]]
entry that was
created by the registration. And because the whole file is saved with the same mechanism,
we also have proper indentation.
If the configuration template includes a settings, and the same setting is passed to the
register
command, the one passed to the register
command takes precedence over the one
specified inside of the config template.
$ cat > /tmp/test-config.template.toml << EOF
[[runners]]
executor = "docker"
EOF
$ sudo gitlab-runner register \
--config /tmp/test-config.toml \
--template-config /tmp/test-config.template.toml \
--non-interactive \
--url https://gitlab.com \
--registration-token __REDACTED__ \
--name test-runner \
--tag-list shell,test \
--locked \
--paused \
--executor shell
Runtime platform arch=amd64 os=linux pid=12359 revision=88310882 version=11.10.0~beta.1251.g88310882
Registering runner... succeeded runner=__REDACTED__
Merging configuration from template file
Runner registered successfully. Feel free to start it, but if it's running already the config should be automatically reloaded!
As we can see, the registration command is specifying the shell
executor, while the template
contains the docker
one. Let’s see what is the final configuration content:
concurrent = 1
check_interval = 0
[session_server]
session_timeout = 1800
[[runners]]
name = "test-runner"
url = "https://gitlab.com"
token = "__REDACTED__"
executor = "shell"
[runners.cache]
[runners.cache.s3]
[runners.cache.gcs]
The configuration set with the register
command options took priority and was
chosen to be placed in the final config.
Help and feedback
If there's something you don't like about this feature
To propose functionality that GitLab does not yet offer
To further help GitLab in shaping new features
If you didn't find what you were looking for
If you want help with something very specific to your use case, and can use some community support
POST ON GITLAB FORUM
If you have problems setting up or using this feature (depending on your GitLab subscription)
REQUEST SUPPORT
To view all GitLab tiers and features or to upgrade
If you want to try all features available in GitLab.com
If you want to try all features available in GitLab self-managed
If you spot an error or a need for improvement and would like to fix it yourself in a merge request
EDIT THIS PAGE
If you would like to suggest an improvement to this doc