• The global section
  • log_format examples (truncated)
    • runner
    • text
    • json
  • How check_interval works
• The [session_server] section
• The [[runners]] section
  • How clone_url works
• The executors
• The shells
  • Use a POSIX-compliant shell
• The [runners.docker] section
  • The [[runners.docker.services]] section
  • Volumes in the [runners.docker] section
    • Example 1: Add a data volume
    • Example 2: Mount a host directory as a data volume
  • Use a private container registry
    • Support for GitLab integrated registry
    • Precedence of Docker authorization resolving
• The [runners.parallels] section
• The [runners.virtualbox] section
• Overriding the base VM image
• The [runners.ssh] section
• The [runners.machine] section
  • The [[runners.machine.autoscaling]] sections
  • Periods syntax
• The [runners.custom] section
• The [runners.cache] section
  • The [runners.cache.s3] section
    • Use KMS key encryption in S3 bucket for runner cache
    • Enable IAM roles for Kubernetes ServiceAccount resources
  • The [runners.cache.gcs] section
  • The [runners.cache.azure] section
• The [runners.kubernetes] section
• Helper image
  • Runner images that use an old version of Alpine Linux
  • Alpine 3.14 and 3.15 pwsh images
  • Helper image registry
  • Override the helper image
    • When using PowerShell Core
• The [runners.custom_build_dir] section
• The [runners.referees] section
  • Use the Metrics Runner referee
  • Configure the Metrics Runner Referee for GitLab Runner
• 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.

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:

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.

[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.