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)


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


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] 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


{"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"}
{"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:

  1. Get check_interval value (10s).
  2. Get list of runners (runner-1, runner-2).
  3. Calculate the sleep interval (10s / 2 = 5s).
  4. Start an infinite loop:
    1. Request a job for runner-1.
    2. Sleep for 5s.
    3. Request a job for runner-2.
    4. Sleep for 5s.
    5. Repeat.

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.

  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 ( or a domain ( The runner uses this information to create a TLS certificate, for a secure connection.

Live sessions are initiated by the web browser. Make sure your web browser can connect to the advertise_address.
Setting Description
listen_address An internal URL for the session server.
advertise_address The URL to ac