- The global section
- The
[session_server]
section -
The
[[runners]]
section - The executors
- The shells
-
The
[runners.docker]
section - The
[runners.parallels]
section - The
[runners.virtualbox]
section - Overriding the base VM image
- The
[runners.ssh]
section -
The
[runners.machine]
section - The
[runners.custom]
section -
The
[runners.cache]
section - The
[runners.kubernetes]
section - Helper image
- The
[runners.custom_build_dir]
section -
The
[runners.referees]
section - Deploy to multiple servers using GitLab CI/CD
Advanced configuration
You can change the behavior of GitLab Runner and of individual registered runners.
To do this, you modify a file called config.toml
, which uses the TOML format.
GitLab Runner does not require a restart when you change most options. This includes parameters
in the [[runners]]
section and most parameters in the global section, except for listen_address
.
If a runner was already registered, you don’t need to register it again.
GitLab Runner checks for configuration modifications every 3 seconds and reloads if necessary.
GitLab Runner also reloads the configuration in response to the SIGHUP
signal.
You can find the config.toml
file in:
-
/etc/gitlab-runner/
on *nix systems when GitLab Runner is executed as root (this is also the path for service configuration) -
~/.gitlab-runner/
on *nix systems when GitLab Runner is executed as non-root -
./
on other systems
The global section
These settings are global. They apply to all runners.
Setting | Description |
---|---|
concurrent |
Limits how many jobs can run concurrently, across all registered runners. Each [[runners]] section can define its own limit, but this value sets a maximum for all of those values combined. For example, a value of 10 means no more than 10 jobs can run concurrently. 0 is forbidden. If you use this value, the runner process exits with a critical error. View how this setting works with the Docker Machine executor (for autoscaling). |
log_level |
Defines the log level. Options are debug , info , warn , error , fatal , and panic . This setting has lower priority than the level set by the command-line arguments --debug , -l , or --log-level . |
log_format |
Specifies the log format. Options are runner , text , and json . This setting has lower priority than the format set by command-line argument --log-format . The default value is runner . |
check_interval |
Defines the interval length, in seconds, between new jobs check. The default value is 3 . If set to 0 or lower, the default value is used. |
sentry_dsn |
Enables tracking of all system level errors to Sentry. |
listen_address |
Defines an address (<host>:<port> ) the Prometheus metrics HTTP server should listen on. |
Configuration example:
concurrent = 4
log_level = "warning"
log_format
examples (truncated)
runner
Runtime platform arch=amd64 os=darwin pid=37300 revision=HEAD version=development version
Starting multi-runner from /etc/gitlab-runner/config.toml... builds=0
WARNING: Running in user-mode.
WARNING: Use sudo for system-mode:
WARNING: $ sudo gitlab-runner...
Configuration loaded builds=0
listen_address not defined, metrics & debug endpoints disabled builds=0
[session_server].listen_address not defined, session endpoints disabled builds=0
text
INFO[0000] Runtime platform arch=amd64 os=darwin pid=37773 revision=HEAD version="development version"
INFO[0000] Starting multi-runner from /etc/gitlab-runner/config.toml... builds=0
WARN[0000] Running in user-mode.
WARN[0000] Use sudo for system-mode:
WARN[0000] $ sudo gitlab-runner...
INFO[0000]
INFO[0000] Configuration loaded builds=0
INFO[0000] listen_address not defined, metrics & debug endpoints disabled builds=0
INFO[0000] [session_server].listen_address not defined, session endpoints disabled builds=0
json
{"arch":"amd64","level":"info","msg":"Runtime platform","os":"darwin","pid":38229,"revision":"HEAD","time":"2020-06-05T15:57:35+02:00","version":"development version"}
{"builds":0,"level":"info","msg":"Starting multi-runner from /etc/gitlab-runner/config.toml...","time":"2020-06-05T15:57:35+02:00"}
{"level":"warning","msg":"Running in user-mode.","time":"2020-06-05T15:57:35+02:00"}
{"level":"warning","msg":"Use sudo for system-mode:","time":"2020-06-05T15:57:35+02:00"}
{"level":"warning","msg":"$ sudo gitlab-runner...","time":"2020-06-05T15:57:35+02:00"}
{"level":"info","msg":"","time":"2020-06-05T15:57:35+02:00"}
{"builds":0,"level":"info","msg":"Configuration loaded","time":"2020-06-05T15:57:35+02:00"}
{"builds":0,"level":"info","msg":"listen_address not defined, metrics \u0026 debug endpoints disabled","time":"2020-06-05T15:57:35+02:00"}
{"builds":0,"level":"info","msg":"[session_server].listen_address not defined, session endpoints disabled","time":"2020-06-05T15:57:35+02:00"}
How check_interval
works
If more than one [[runners]]
section exists in config.toml
,
the interval between requests to GitLab are more frequent than you might expect. GitLab Runner
contains a loop that constantly schedules a request to the GitLab instance it’s configured for.
GitLab Runner tries to ensure that subsequent requests for each runner are done in the specified interval.
To do this, it divides the value of check_interval
by the number of [[runners]]
sections. The loop
iterates over all sections, schedules a request for each, and sleeps for the calculated amount
of time. Things get interesting when the runners are tied to a different GitLab instance.
Consider the following example.
If you set check_interval = 10
, and there are two runners (runner-1
and runner-2
),
a request is made each 10 seconds. Here is an example of the loop in this case:
- Get
check_interval
value (10s
). - Get list of runners (
runner-1
,runner-2
). - Calculate the sleep interval (
10s / 2 = 5s
). - Start an infinite loop:
- Request a job for
runner-1
. - Sleep for
5s
. - Request a job for
runner-2
. - Sleep for
5s
. - Repeat.
- Request a job for
In this example, a request from the runner’s process is made every 5 seconds.
If runner-1
and runner-2
are connected to the same
GitLab instance, this GitLab instance also receives a new request from this runner
every 5 seconds.
Between the first request for runner-1
and second request for runner-1
there are two sleep periods. Each one takes 5 seconds, so it’s approximately 10 seconds between subsequent requests for runner-1
.
The same applies for runner-2
.
If you define more runners, the sleep interval is smaller. However, a request for a runner is repeated after all requests for the other runners and their sleep periods are called.
The [session_server]
section
The [session_server]
section lets users interact with jobs, for example, in the
interactive web terminal.
The [session_server]
section should be specified at the root level, not per runner.
It should be defined outside the [[runners]]
section.
[session_server]
listen_address = "[::]:8093" # listen on all available interfaces on port 8093
advertise_address = "runner-host-name.tld:8093"
session_timeout = 1800
Both listen_address
and advertise_address
should be in the form
of host:port
, where host
may be an IP address (127.0.0.1:8093
)
or a domain (my-runner.example.com:8093
). The runner uses this information to create
a TLS certificate, for a secure connection.
advertise_address
.Setting | Description |
---|---|
listen_address |
An internal URL for the session server. |
advertise_address |
The URL to ac |