1--- 2stage: Verify 3group: Runner 4info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers 5--- 6 7# Advanced configuration 8 9You can change the behavior of GitLab Runner and of individual registered runners. 10 11To do this, you modify a file called `config.toml`, which uses the [TOML](https://github.com/toml-lang/toml) format. 12 13GitLab Runner does not require a restart when you change most options. This includes parameters 14in the `[[runners]]` section and most parameters in the global section, except for `listen_address`. 15If a runner was already registered, you don't need to register it again. 16 17GitLab Runner checks for configuration modifications every 3 seconds and reloads if necessary. 18GitLab Runner also reloads the configuration in response to the `SIGHUP` signal. 19 20You can find the `config.toml` file in: 21 22- `/etc/gitlab-runner/` on \*nix systems when GitLab Runner is 23 executed as root (**this is also the path for service configuration**) 24- `~/.gitlab-runner/` on \*nix systems when GitLab Runner is 25 executed as non-root 26- `./` on other systems 27 28## The global section 29 30These settings are global. They apply to all runners. 31 32| Setting | Description | 33| ------- | ----------- | 34| `concurrent` | Limits how many jobs can run concurrently. The maximum number is all defined runners. `0` **does not** mean unlimited. | 35| `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`. | 36| `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`. | 37| `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. | 38| `sentry_dsn` | Enables tracking of all system level errors to Sentry. | 39| `listen_address` | Defines an address (`<host>:<port>`) the Prometheus metrics HTTP server should listen on. | 40 41Configuration example: 42 43```toml 44concurrent = 4 45log_level = "warning" 46``` 47 48### `log_format` examples (truncated) 49 50#### `runner` 51 52```shell 53Runtime platform arch=amd64 os=darwin pid=37300 revision=HEAD version=development version 54Starting multi-runner from /etc/gitlab-runner/config.toml... builds=0 55WARNING: Running in user-mode. 56WARNING: Use sudo for system-mode: 57WARNING: $ sudo gitlab-runner... 58 59Configuration loaded builds=0 60listen_address not defined, metrics & debug endpoints disabled builds=0 61[session_server].listen_address not defined, session endpoints disabled builds=0 62``` 63 64#### `text` 65 66```shell 67INFO[0000] Runtime platform arch=amd64 os=darwin pid=37773 revision=HEAD version="development version" 68INFO[0000] Starting multi-runner from /etc/gitlab-runner/config.toml... builds=0 69WARN[0000] Running in user-mode. 70WARN[0000] Use sudo for system-mode: 71WARN[0000] $ sudo gitlab-runner... 72INFO[0000] 73INFO[0000] Configuration loaded builds=0 74INFO[0000] listen_address not defined, metrics & debug endpoints disabled builds=0 75INFO[0000] [session_server].listen_address not defined, session endpoints disabled builds=0 76``` 77 78#### `json` 79 80```shell 81{"arch":"amd64","level":"info","msg":"Runtime platform","os":"darwin","pid":38229,"revision":"HEAD","time":"2020-06-05T15:57:35+02:00","version":"development version"} 82{"builds":0,"level":"info","msg":"Starting multi-runner from /etc/gitlab-runner/config.toml...","time":"2020-06-05T15:57:35+02:00"} 83{"level":"warning","msg":"Running in user-mode.","time":"2020-06-05T15:57:35+02:00"} 84{"level":"warning","msg":"Use sudo for system-mode:","time":"2020-06-05T15:57:35+02:00"} 85{"level":"warning","msg":"$ sudo gitlab-runner...","time":"2020-06-05T15:57:35+02:00"} 86{"level":"info","msg":"","time":"2020-06-05T15:57:35+02:00"} 87{"builds":0,"level":"info","msg":"Configuration loaded","time":"2020-06-05T15:57:35+02:00"} 88{"builds":0,"level":"info","msg":"listen_address not defined, metrics \u0026 debug endpoints disabled","time":"2020-06-05T15:57:35+02:00"} 89{"builds":0,"level":"info","msg":"[session_server].listen_address not defined, session endpoints disabled","time":"2020-06-05T15:57:35+02:00"} 90``` 91 92### How `check_interval` works 93 94If more than one `[[runners]]` section exists in `config.toml`, 95the interval between requests to GitLab are more frequent than you might expect. GitLab Runner 96contains a loop that constantly schedules a request to the GitLab instance it's configured for. 97 98GitLab Runner tries to ensure that subsequent requests for each runner are done in the specified interval. 99To do this, it divides the value of `check_interval` by the number of `[[runners]]` sections. The loop 100iterates over all sections, schedules a request for each, and sleeps for the calculated amount 101of time. Things get interesting when the runners are tied to a different GitLab instance. 102Consider the following example. 103 104If you set `check_interval = 10`, and there are two runners (`runner-1` and `runner-2`), 105a request is made each 10 seconds. Here is an example of the loop in this case: 106 1071. Get `check_interval` value (`10s`). 1081. Get list of runners (`runner-1`, `runner-2`). 1091. Calculate the sleep interval (`10s / 2 = 5s`). 1101. Start an infinite loop: 111 1. Request a job for `runner-1`. 112 1. Sleep for `5s`. 113 1. Request a job for `runner-2`. 114 1. Sleep for `5s`. 115 1. Repeat. 116 117In this example, a request from the runner's process is made every 5 seconds. 118If `runner-1` and `runner-2` are connected to the same 119GitLab instance, this GitLab instance also receives a new request from this runner 120every 5 seconds. 121 122Between the first request for `runner-1` and second request for `runner-1` 123there are two sleep periods. Each one takes 5 seconds, so it's approximately 10 seconds between subsequent requests for `runner-1`. 124The same applies for `runner-2`. 125 126If you define more runners, the sleep interval is smaller. However, a request for a runner is 127repeated after all requests for the other runners and their sleep periods are called. 128 129## The `[session_server]` section 130 131NOTE: 132The `session_server` section is not supported by the 133[`gitlab-runner` Helm chart](https://docs.gitlab.com/charts/charts/gitlab/gitlab-runner/index.html), 134but [an issue exists to track this work](https://gitlab.com/gitlab-org/charts/gitlab-runner/-/issues/79). 135 136The `[session_server]` section lets users interact with jobs, for example, in the 137[interactive web terminal](https://docs.gitlab.com/ee/ci/interactive_web_terminal/index.html). 138 139The `[session_server]` section should be specified at the root level, not per runner. 140It should be defined outside the `[[runners]]` section. 141 142```toml 143[session_server] 144 listen_address = "[::]:8093" # listen on all available interfaces on port 8093 145 advertise_address = "runner-host-name.tld:8093" 146 session_timeout = 1800 147``` 148 149Both `listen_address` and `advertise_address` should be in the form 150of `host:port`, where `host` may be an IP address (`127.0.0.1:8093`) 151or a domain (`my-runner.example.com:8093`). The runner uses this information to create 152a TLS certificate, for a secure connection. 153 154| Setting | Description | 155| ------- | ----------- | 156| `listen_address` | An internal URL for the session server. | 157| `advertise_address`| The URL to access the session server. GitLab Runner exposes it to GitLab. If not defined, `listen_address` is used. | 158| `session_timeout` | Number of seconds the session can stay active after the job completes. The timeout blocks the job from finishing. Default is `1800` (30 minutes). | 159 160To disable the session server and terminal support, delete the `[session_server]` section. 161 162If you are using the GitLab Runner Docker image, you must expose port `8093` by 163adding `-p 8093:8093` to your [`docker run` command](../install/docker.md). 164 165## The `[[runners]]` section 166 167Each `[[runners]]` section defines one runner. 168 169| Setting | Description | 170| ------- | ----------- | 171| `name` | The runner's description. Informational only. | 172| `url` | GitLab instance URL. | 173| `token` | The runner's special token (not to be confused with the registration token). | 174| `tls-ca-file` | When using HTTPS, file that contains the certificates to verify the peer. See [Self-signed certificates or custom Certification Authorities documentation](tls-self-signed.md). | 175| `tls-cert-file` | When using HTTPS, file that contains the certificate to authenticate with the peer. | 176| `tls-key-file` | When using HTTPS, file that contains the private key to authenticate with the peer. | 177| `limit` | Limit how many jobs can be handled concurrently by this token. `0` (default) means do not limit. | 178| `executor` | Select how a project should be built. | 179| `shell` | Name of shell to generate the script. Default value is [platform dependent](../shells/index.md#overview). | 180| `builds_dir` | Absolute path to a directory where builds are stored in the context of the selected executor. For example, locally, Docker, or SSH. | 181| `cache_dir` | Absolute path to a directory where build caches are stored in context of selected executor. For example, locally, Docker, or SSH. If the `docker` executor is used, this directory needs to be included in its `volumes` parameter. | 182| `environment` | Append or overwrite environment variables. | 183| `request_concurrency` | Limit number of concurrent requests for new jobs from GitLab. Default is `1`. | 184| `output_limit` | Maximum build log size in kilobytes. Default is `4096` (4MB). | 185| `pre_clone_script` | Commands to be executed on the runner before cloning the Git repository. Use it to adjust the Git client configuration first, for example. To insert multiple commands, use a (triple-quoted) multi-line string or `\n` character. | 186| `pre_build_script` | Commands to be executed on the runner after cloning the Git repository, but before executing the build. To insert multiple commands, use a (triple-quoted) multi-line string or `\n` character. | 187| `post_build_script` | Commands to be executed on the runner just after executing the build, but before executing `after_script`. To insert multiple commands, use a (triple-quoted) multi-line string or `\n` character. | 188| `clone_url` | Overwrite the URL for the GitLab instance. Used only if the runner can't connect to the GitLab URL. | 189| `debug_trace_disabled` | Disables the `CI_DEBUG_TRACE` feature. When set to `true`, then debug log (trace) remains disabled, even if `CI_DEBUG_TRACE` is set to `true` by the user. | 190| `referees` | Extra job monitoring workers that pass their results as job artifacts to GitLab. | 191 192Example: 193 194```toml 195[[runners]] 196 name = "ruby-2.6-docker" 197 url = "https://CI/" 198 token = "TOKEN" 199 limit = 0 200 executor = "docker" 201 builds_dir = "" 202 shell = "" 203 environment = ["ENV=value", "LC_ALL=en_US.UTF-8"] 204 clone_url = "http://gitlab.example.local" 205``` 206 207### How `clone_url` works 208 209When the GitLab instance is available at a URL that the runner can't use, 210you can configure a `clone_url`. 211 212For example, a firewall might prevent the runner from reaching the URL. 213If the runner can reach the node on `192.168.1.23`, set the `clone_url` to `http://192.168.1.23`. 214 215If the `clone_url` is set, the runner constructs a clone URL in the form 216of `http://gitlab-ci-token:s3cr3tt0k3n@192.168.1.23/namespace/project.git`. 217 218## The executors 219 220The following executors are available. 221 222| Executor | Required configuration | Where jobs run | 223|-|-|-| 224| `shell` | | Local shell. The default executor. | 225| `docker` | `[runners.docker]` and [Docker Engine](https://docs.docker.com/engine/) | A Docker container. | 226| `docker-windows` | `[runners.docker]` and [Docker Engine](https://docs.docker.com/engine/) | A Windows Docker container. | 227| `docker-ssh` | `[runners.docker]`, `[runners.ssh]`, and [Docker Engine](https://docs.docker.com/engine/) | A Docker container, but connect with SSH. **The Docker container runs on the local machine. This setting changes how the commands are run inside that container. If you want to run Docker commands on an external machine, change the `host` parameter in the `runners.docker` section.** | 228| `ssh` | `[runners.ssh]` | SSH, remotely. | 229| `parallels` | `[runners.parallels]` and `[runners.ssh]` | Parallels VM, but connect with SSH. | 230| `virtualbox` | `[runners.virtualbox]` and `[runners.ssh]` | VirtualBox VM, but connect with SSH. | 231| `docker+machine` | `[runners.docker]` and `[runners.machine]` | Like `docker`, but use [auto-scaled Docker machines](autoscale.md). | 232| `docker-ssh+machine` | `[runners.docker]` and `[runners.machine]` | Like `docker-ssh`, but use [auto-scaled Docker machines](autoscale.md). | 233| `kubernetes` | `[runners.kubernetes]` | Kubernetes pods. | 234 235## The shells 236 237The available shells can run on different platforms. 238 239| Shell | Description | 240| ----- | ----------- | 241| `bash` | Generate Bash (Bourne-shell) script. All commands executed in Bash context. Default for all Unix systems. | 242| `sh` | Generate Sh (Bourne-shell) script. All commands executed in Sh context. The fallback for `bash` for all Unix systems. | 243| `powershell` | Generate PowerShell script. All commands are executed in PowerShell Desktop context. In GitLab Runner 12.0-13.12, this is the default for Windows. | 244| `pwsh` | Generate PowerShell script. All commands are executed in PowerShell Core context. In GitLab Runner 14.0 and later, this is the default for Windows. | 245 246## The `[runners.docker]` section 247 248This defines the Docker Container parameters. 249 250| Parameter | Description | 251| --------- | ----------- | 252| `allowed_images` | Wildcard list of images that can be specified in the `.gitlab-ci.yml` file. If not present, all images are allowed (equivalent to `["*/*:*"]`). | 253| `allowed_services` | Wildcard list of services that can be specified in the `.gitlab-ci.yml` file. If not present, all images are allowed (equivalent to `["*/*:*"]`). | 254| `cache_dir` | Directory where Docker caches should be stored. This path can be absolute or relative to current working directory. See `disable_cache` for more information. | 255| `cap_add` | Add additional Linux capabilities to the container. | 256| `cap_drop` | Drop additional Linux capabilities from the container. | 257| `cpuset_cpus` | The control group's `CpusetCpus`. A string. | 258| `cpu_shares` | Number of CPU shares used to set relative CPU usage. Default is `1024`. | 259| `cpus` | Number of CPUs (available in Docker 1.13 or later. A string. | 260| `devices` | Share additional host devices with the container. | 261| `disable_cache` | The Docker executor has two levels of caching: a global one (like any other executor) and a local cache based on Docker volumes. This configuration flag acts only on the local one which disables the use of automatically created (not mapped to a host directory) cache volumes. In other words, it only prevents creating a container that holds temporary files of builds, it does not disable the cache if the runner is configured in [distributed cache mode](autoscale.md#distributed-runners-caching). | 262| `disable_entrypoint_overwrite` | Disable the image entrypoint overwriting. | 263| `dns` | A list of DNS servers for the container to use. | 264| `dns_search` | A list of DNS search domains. | 265| `extra_hosts` | Hosts that should be defined in container environment. | 266| `gpus` | GPU devices for Docker container. Uses the same format as the `docker` cli. View details in the [Docker documentation](https://docs.docker.com/config/containers/resource_constraints/#gpu). | 267| `helper_image` | (Advanced) [The default helper image](#helper-image) used to clone repositories and upload artifacts. | 268| `helper_image_flavor` | Sets the helper image flavor (`alpine` or `ubuntu`). Defaults to `alpine`. | 269| `host` | Custom Docker endpoint. Default is `DOCKER_HOST` environment or `unix:///var/run/docker.sock`. | 270| `hostname` | Custom hostname for the Docker container. | 271| `image` | The image to run jobs with. | 272| `links` | Containers that should be linked with container that runs the job. | 273| `memory` | The memory limit. A string. | 274| `memory_swap` | The total memory limit. A string. | 275| `memory_reservation` | The memory soft limit. A string. | 276| `network_mode` | Add container to a custom network. | 277| `oom_kill_disable` | If an out-of-memory (OOM) error occurs, do not kill processes in a container. | 278| `oom_score_adjust` | OOM score adjustment. Positive means kill earlier. | 279| `privileged` | Make the container run in privileged mode. Insecure. | 280| `pull_policy` | The image pull policy: `never`, `if-not-present` or `always` (default). View details in the [pull policies documentation](../executors/docker.md#how-pull-policies-work). You can also add [multiple pull policies](../executors/docker.md#using-multiple-pull-policies). | 281| `runtime` | The runtime for the Docker container. | 282| `security_opt` | Security options (--security-opt in `docker run`). Takes a list of `:` separated key/values. | 283| `shm_size` | Shared memory size for images (in bytes). | 284| `sysctls` | The `sysctl` options. | 285| `tls_cert_path` | A directory where `ca.pem`, `cert.pem` or `key.pem` are stored and used to make a secure TLS connection to Docker. Useful in `boot2docker`. | 286| `tls_verify` | Enable or disable TLS verification of connections to Docker daemon. Disabled by default. | 287| `userns_mode` | The user namespace mode for the container and Docker services when user namespace remapping option is enabled. Available in Docker 1.10 or later. | 288| `volumes` | Additional volumes that should be mounted. Same syntax as the Docker `-v` flag. | 289| `volumes_from` | A list of volumes to inherit from another container in the form `<container name>[:<ro|rw>]`. Access level defaults to read-write, but can be manually set to `ro` (read-only) or `rw` (read-write). | 290| `volume_driver` | The volume driver to use for the container. | 291| `wait_for_services_timeout` | How long to wait for Docker services. Set to `0` to disable. Default is `30`. | 292 293### The `[[runners.docker.services]]` section 294 295Specify additional services that should be run with the job. Visit the 296[Docker Registry](https://hub.docker.com) for the list of available applications. 297Each service runs in a separate container and is linked to the job. 298 299| Parameter | Description | 300| --------- | ----------- | 301| `name` | The name of the image to be run as a service. | 302| `alias` | Additional [alias name](https://docs.gitlab.com/ee/ci/docker/using_docker_images.html#available-settings-for-services) that can be used to access the service .| 303| `entrypoint` | Command or script that should be executed as the container’s entrypoint. The syntax is similar to [Dockerfile’s ENTRYPOINT](https://docs.docker.com/engine/reference/builder/#entrypoint) directive, where each shell token is a separate string in the array. Introduced in [GitLab Runner 13.6](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/27173). | 304| `command` | Command or script that should be used as the container’s command. The syntax is similar to [Dockerfile’s CMD](https://docs.docker.com/engine/reference/builder/#cmd) directive, where each shell token is a separate string in the array. Introduced in [GitLab Runner 13.6](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/27173). | 305 306Example: 307 308```toml 309[runners.docker] 310 host = "" 311 hostname = "" 312 tls_cert_path = "/Users/ayufan/.boot2docker/certs" 313 image = "ruby:2.6" 314 memory = "128m" 315 memory_swap = "256m" 316 memory_reservation = "64m" 317 oom_kill_disable = false 318 cpuset_cpus = "0,1" 319 cpus = "2" 320 dns = ["8.8.8.8"] 321 dns_search = [""] 322 privileged = false 323 userns_mode = "host" 324 cap_add = ["NET_ADMIN"] 325 cap_drop = ["DAC_OVERRIDE"] 326 devices = ["/dev/net/tun"] 327 disable_cache = false 328 wait_for_services_timeout = 30 329 cache_dir = "" 330 volumes = ["/data", "/home/project/cache"] 331 extra_hosts = ["other-host:127.0.0.1"] 332 shm_size = 300000 333 volumes_from = ["storage_container:ro"] 334 links = ["mysql_container:mysql"] 335 allowed_images = ["ruby:*", "python:*", "php:*"] 336 allowed_services = ["postgres:9", "redis:*", "mysql:*"] 337 [[runners.docker.services]] 338 name = "registry.example.com/svc1" 339 alias = "svc1" 340 entrypoint = ["entrypoint.sh"] 341 command = ["executable","param1","param2"] 342 [[runners.docker.services]] 343 name = "redis:2.8" 344 alias = "cache" 345 [[runners.docker.services]] 346 name = "postgres:9" 347 alias = "postgres-db" 348 [runners.docker.sysctls] 349 "net.ipv4.ip_forward" = "1" 350``` 351 352### Volumes in the `[runners.docker]` section 353 354[View the complete guide of Docker volume usage](https://docs.docker.com/userguide/dockervolumes/). 355 356The following examples show how to specify volumes in the `[runners.docker]` section. 357 358#### Example 1: Add a data volume 359 360A data volume is a specially-designated directory in one or more containers 361that bypasses the Union File System. Data volumes are designed to persist data, 362independent of the container's life cycle. 363 364```toml 365[runners.docker] 366 host = "" 367 hostname = "" 368 tls_cert_path = "/Users/ayufan/.boot2docker/certs" 369 image = "ruby:2.6" 370 privileged = false 371 disable_cache = true 372 volumes = ["/path/to/volume/in/container"] 373``` 374 375This example creates a new volume in the container at `/path/to/volume/in/container`. 376 377#### Example 2: Mount a host directory as a data volume 378 379When you want to store directories outside the container, you can mount 380a directory from your Docker daemon's host into a container: 381 382```toml 383[runners.docker] 384 host = "" 385 hostname = "" 386 tls_cert_path = "/Users/ayufan/.boot2docker/certs" 387 image = "ruby:2.6" 388 privileged = false 389 disable_cache = true 390 volumes = ["/path/to/bind/from/host:/path/to/bind/in/container:rw"] 391``` 392 393This example uses `/path/to/bind/from/host` of the CI/CD host in the container at 394`/path/to/bind/in/container`. 395 396GitLab Runner 11.11 and later [mount the host directory](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/1261) 397for the defined [services](https://docs.gitlab.com/ee/ci/services/) as 398well. 399 400### Use a private container registry 401 402To use private registries as a source of images for your jobs, 403you can set the authorization configuration in a [CI/CD variable](https://docs.gitlab.com/ee/ci/variables/) 404named `DOCKER_AUTH_CONFIG`. You can set the variable in the project's CI/CD settings 405or in the `config.toml` file. 406 407Using private registries with the `if-not-present` pull policy may introduce 408[security implications](../security/index.md#usage-of-private-docker-images-with-if-not-present-pull-policy). 409To fully understand how pull policies work, 410read the [pull policies documentation](../executors/docker.md#how-pull-policies-work). 411 412For a detailed example, visit the [Using Docker images documentation](https://docs.gitlab.com/ee/ci/docker/using_docker_images.html#define-an-image-from-a-private-container-registry). 413 414The steps performed by the runner can be summed up as: 415 4161. The registry name is found from the image name. 4171. If the value is not empty, the executor searches for the authentication 418 configuration for this registry. 4191. Finally, if an authentication corresponding to the specified registry is 420 found, subsequent pulls makes use of it. 421 422Now that the runner is set up to authenticate against your private registry, 423learn [how to configure the `.gitlab-ci.yml` file](https://docs.gitlab.com/ee/ci/yaml/README.html#image) to use that 424registry. 425 426#### Support for GitLab integrated registry 427 428GitLab sends credentials for its integrated 429registry along with the job's data. These credentials are automatically 430added to the registry's authorization parameters list. 431 432After this step, authorization against the registry proceeds similarly to 433configuration added with the `DOCKER_AUTH_CONFIG` variable. 434 435In your jobs, you can use any image from your GitLab integrated 436registry, even if the image is private or protected. For information on the images jobs have access to, read the 437[CI/CD job token documentation](https://docs.gitlab.com/ee/api/README.html#gitlab-cicd-job-token) documentation. 438 439#### Precedence of Docker authorization resolving 440 441As described earlier, GitLab Runner can authorize Docker against a registry by 442using credentials sent in different way. To find a proper registry, the following 443precedence is taken into account: 444 4451. Credentials configured with `DOCKER_AUTH_CONFIG`. 4461. Credentials configured locally on the GitLab Runner host with `~/.docker/config.json` 447 or `~/.dockercfg` files (for example, by running `docker login` on the host). 4481. Credentials sent by default with a job's payload (for example, credentials for the *integrated 449 registry* described earlier). 450 451The first credentials found for the registry are used. So for example, 452if you add credentials for the *integrated registry* with the 453`DOCKER_AUTH_CONFIG` variable, then the default credentials are overridden. 454 455#### Restrict `allowed_images` to private registry 456 457You can restrict access so that your jobs run on Docker images 458from your private Docker registry. For example: 459 460```toml 461[runners.docker] 462 ... 463 allowed_images = ["my.registry.tld:5000/*:*"] 464``` 465 466## The `[runners.parallels]` section 467 468The following parameters are for Parallels. 469 470| Parameter | Description | 471| --------- | ----------- | 472| `base_name` | Name of Parallels VM that is cloned. | 473| `template_name` | Custom name of Parallels VM linked template. Optional. | 474| `disable_snapshots` | If disabled, the VMs are destroyed when the jobs are done. | 475 476Example: 477 478```toml 479[runners.parallels] 480 base_name = "my-parallels-image" 481 template_name = "" 482 disable_snapshots = false 483``` 484 485## The `[runners.virtualbox]` section 486 487The following parameters are for VirtualBox. This executor relies on the 488`vboxmanage` executable to control VirtualBox machines, so you have to adjust 489your `PATH` environment variable on Windows hosts: 490`PATH=%PATH%;C:\Program Files\Oracle\VirtualBox`. 491 492| Parameter | Explanation | 493| --------- | ----------- | 494| `base_name` | Name of the VirtualBox VM that is cloned. | 495| `base_snapshot` | Name or UUID of a specific snapshot of the VM to create a linked clone from. If this value is empty or omitted, the current snapshot is used. If no current snapshot exists, one is created. Unless `disable_snapshots` is true, in which case a full clone of the base VM is made. | 496| `base_folder` | Folder to save the new VM in. If this value is empty or omitted, the default VM folder is used. | 497| `disable_snapshots` | If disabled, the VMs are destroyed when the jobs are done. | 498 499Example: 500 501```toml 502[runners.virtualbox] 503 base_name = "my-virtualbox-image" 504 base_snapshot = "my-image-snapshot" 505 disable_snapshots = false 506``` 507 508## The `[runners.ssh]` section 509 510The following parameters define the SSH connection. 511 512| Parameter | Description | 513| ---------- | ----------- | 514| `host` | Where to connect. Overridden when you use `docker-ssh`. | 515| `port` | Port. Default is `22`. | 516| `user` | Username. | 517| `password` | Password. | 518| `identity_file` | File path to SSH private key (`id_rsa`, `id_dsa`, or `id_edcsa`). The file must be stored unencrypted. | 519 520Example: 521 522```toml 523[runners.ssh] 524 host = "my-production-server" 525 port = "22" 526 user = "root" 527 password = "production-server-password" 528 identity_file = "" 529``` 530 531## The `[runners.machine]` section 532 533> Added in GitLab Runner v1.1.0. 534 535The following parameters define the Docker Machine-based autoscaling feature. More details can be 536found in the separate [runner autoscale documentation](autoscale.md). 537 538| Parameter | Description | 539|---------------------|-------------| 540| `MaxGrowthRate` | The maximum number of machines that can be added to the runner in parallel. Default is `0` (no limit). | 541| `IdleCount` | Number of machines that need to be created and waiting in _Idle_ state. | 542| `IdleTime` | Time (in seconds) for machine to be in _Idle_ state before it is removed. | 543| `[[runners.machine.autoscaling]]` | Multiple sections, each containing overrides for autoscaling configuration. The last section with an expression that matches the current time is selected. | 544| `OffPeakPeriods` | Deprecated: Time periods when the scheduler is in the OffPeak mode. An array of cron-style patterns (described [below](#periods-syntax)). | 545| `OffPeakTimezone` | Deprecated: Timezone for the times given in OffPeakPeriods. A timezone string like `Europe/Berlin`. Defaults to the locale system setting of the host if omitted or empty. GitLab Runner attempts to locate the timezone database in the directory or uncompressed zip file named by the `ZONEINFO` environment variable, then looks in known installation locations on Unix systems, and finally looks in `$GOROOT/lib/time/zoneinfo.zip`. | 546| `OffPeakIdleCount` | Deprecated: Like `IdleCount`, but for _Off Peak_ time periods. | 547| `OffPeakIdleTime` | Deprecated: Like `IdleTime`, but for _Off Peak_ time periods. | 548| `MaxBuilds` | Maximum job (build) count before machine is removed. | 549| `MachineName` | Name of the machine. It **must** contain `%s`, which is replaced with a unique machine identifier. | 550| `MachineDriver` | Docker Machine `driver`. View details in the [Docker Machine configuration section](autoscale.md#supported-cloud-providers). | 551| `MachineOptions` | Docker Machine options. View details in the [Docker Machine configuration section](autoscale.md#supported-cloud-providers). | 552 553### The `[[runners.machine.autoscaling]]` sections 554 555| Parameter | Description | 556|---------------------|-------------| 557| `Periods` | Time periods during which this schedule is active. An array of cron-style patterns (described [below](#periods-syntax)). 558| `IdleCount` | Number of machines that need to be created and waiting in _Idle_ state. | 559| `IdleTime` | Time (in seconds) for a machine to be in _Idle_ state before it is removed. | 560| `Timezone` | Timezone for the times given in `Periods`. A timezone string like `Europe/Berlin`. Defaults to the locale system setting of the host if omitted or empty. GitLab Runner attempts to locate the timezone database in the directory or uncompressed zip file named by the `ZONEINFO` environment variable, then looks in known installation locations on Unix systems, and finally looks in `$GOROOT/lib/time/zoneinfo.zip`. | 561 562Example: 563 564```toml 565[runners.machine] 566 IdleCount = 5 567 IdleTime = 600 568 MaxBuilds = 100 569 MachineName = "auto-scale-%s" 570 MachineDriver = "google" # Refer to Docker Machine docs on how to authenticate: https://docs.docker.com/machine/drivers/gce/#credentials 571 MachineOptions = [ 572 # Additional machine options can be added using the Google Compute Engine driver. 573 # If you experience problems with an unreachable host (ex. "Waiting for SSH"), 574 # you should remove optional parameters to help with debugging. 575 # https://docs.docker.com/machine/drivers/gce/ 576 "google-project=GOOGLE-PROJECT-ID", 577 "google-zone=GOOGLE-ZONE", # e.g. 'us-central1-a', full list in https://cloud.google.com/compute/docs/regions-zones/ 578 ] 579 [[runners.machine.autoscaling]] 580 Periods = ["* * 9-17 * * mon-fri *"] 581 IdleCount = 50 582 IdleTime = 3600 583 Timezone = "UTC" 584 [[runners.machine.autoscaling]] 585 Periods = ["* * * * * sat,sun *"] 586 IdleCount = 5 587 IdleTime = 60 588 Timezone = "UTC" 589``` 590 591### Periods syntax 592 593The `Periods` setting contains an array of string patterns of 594time periods represented in a cron-style format. The line contains 595following fields: 596 597```plaintext 598[second] [minute] [hour] [day of month] [month] [day of week] [year] 599``` 600 601Like in the standard cron configuration file, the fields can contain single 602values, ranges, lists, and asterisks. View [a detailed description of the syntax](https://github.com/gorhill/cronexpr#implementation). 603 604## The `[runners.custom]` section 605 606The following parameters define configuration for the [custom executor](../executors/custom.md). 607 608| Parameter | Type | Description | 609|-------------------------|--------------|-------------| 610| `config_exec` | string | Path to an executable, so a user can override some configuration settings before the job starts. These values override the ones set in the [`[[runners]]`](#the-runners-section) section. [The custom executor documentation](../executors/custom.md#config) has the full list. | 611| `config_args` | string array | First set of arguments passed to the `config_exec` executable. | 612| `config_exec_timeout` | integer | Timeout, in seconds, for `config_exec` to finish execution. Default is 3600 seconds (1 hour). | 613| `prepare_exec` | string | Path to an executable to prepare the environment. | 614| `prepare_args` | string array | First set of arguments passed to the `prepare_exec` executable. | 615| `prepare_exec_timeout` | integer | Timeout, in seconds, for `prepare_exec` to finish execution. Default is 3600 seconds (1 hour). | 616| `run_exec` | string | **Required.** Path to an executable to run scripts in the environments. For example, the clone and build script. | 617| `run_args` | string array | First set of arguments passed to the `run_exec` executable. | 618| `cleanup_exec` | string | Path to an executable to clean up the environment. | 619| `cleanup_args` | string array | First set of arguments passed to the `cleanup_exec` executable. | 620| `cleanup_exec_timeout` | integer | Timeout, in seconds, for `cleanup_exec` to finish execution. Default is 3600 seconds (1 hour). | 621| `graceful_kill_timeout` | integer | Time to wait, in seconds, for `prepare_exec` and `cleanup_exec` if they are terminated (for example, during job cancellation). After this timeout, the process is killed. Default is 600 seconds (10 minutes). | 622| `force_kill_timeout` | integer | Time to wait, in seconds, after the kill signal is sent to the script. Default is 600 seconds (10 minutes). | 623 624## The `[runners.cache]` section 625 626> Introduced in GitLab Runner 1.1.0. 627 628The following parameters define the distributed cache feature. View details 629in the [runner autoscale documentation](autoscale.md#distributed-runners-caching). 630 631| Parameter | Type | Description | 632|------------------|------------------|-------------| 633| `Type` | string | One of: `s3`, `gcs`, `azure`. | 634| `Path` | string | Name of the path to prepend to the cache URL. | 635| `Shared` | boolean | Enables cache sharing between runners. Default is `false`. | 636 637WARNING: 638In GitLab Runner 11.3, the configuration parameters related to S3 were moved to a dedicated `[runners.cache.s3]` section. 639The configuration with S3 configured directly in `[runners.cache]` was deprecated. 640**In GitLab Runner 12.0, the configuration syntax was removed and is no longer supported**. 641 642The cache mechanism uses pre-signed URLs to upload and download cache. URLs are signed by GitLab Runner on its own instance. 643It does not matter if the job's script (including the cache upload/download script) are executed on local or external 644machines. For example, `shell` or `docker` executors run their scripts on the same 645machine where the GitLab Runner process is running. At the same time, `virtualbox` or `docker+machine` 646connects to a separate VM to execute the script. This process is for security reasons: 647minimizing the possibility of leaking the cache adapter's credentials. 648 649If the [S3 cache adapter](#the-runnerscaches3-section) is configured to use 650an IAM instance profile, the adapter uses the profile attached to the GitLab Runner machine. 651Similarly for [GCS cache adapter](#the-runnerscachegcs-section), if configured to 652use the `CredentialsFile`. The file needs to be present on the GitLab Runner machine. 653 654This table lists `config.toml`, CLI options, and ENV variables for `register`. 655 656| Setting | TOML field | CLI option for `register` | ENV for `register` | Before 12.0.0 TOML field | Before 12.0.0 CLI option | Before 12.0.0 ENV | 657|-----------------------|------------------------------------------|--------------------------------|-----------------------------------|-------------------------------------|--------------------------|---------------------------| 658| `Type` | `[runners.cache] -> Type` | `--cache-type` | `$CACHE_TYPE` | | | | 659| `Path` | `[runners.cache] -> Path` | `--cache-path` | `$CACHE_PATH` | | `--cache-s3-cache-path` | `$S3_CACHE_PATH` | 660| `Shared` | `[runners.cache] -> Shared` | `--cache-shared` | `$CACHE_SHARED` | | `--cache-cache-shared` | | 661| `S3.ServerAddress` | `[runners.cache.s3] -> ServerAddress` | `--cache-s3-server-address` | `$CACHE_S3_SERVER_ADDRESS` | `[runners.cache] -> ServerAddress` | | `$S3_SERVER_ADDRESS` | 662| `S3.AccessKey` | `[runners.cache.s3] -> AccessKey` | `--cache-s3-access-key` | `$CACHE_S3_ACCESS_KEY` | `[runners.cache] -> AccessKey` | | `$S3_ACCESS_KEY` | 663| `S3.SecretKey` | `[runners.cache.s3] -> SecretKey` | `--cache-s3-secret-key` | `$CACHE_S3_SECRET_KEY` | `[runners.cache] -> SecretKey` | | `$S3_SECRET_KEY` | 664| `S3.BucketName` | `[runners.cache.s3] -> BucketName` | `--cache-s3-bucket-name` | `$CACHE_S3_BUCKET_NAME` | `[runners.cache] -> BucketName` | | `$S3_BUCKET_NAME` | 665| `S3.BucketLocation` | `[runners.cache.s3] -> BucketLocation` | `--cache-s3-bucket-location` | `$CACHE_S3_BUCKET_LOCATION` | `[runners.cache] -> BucketLocation` | | `$S3_BUCKET_LOCATION` | 666| `S3.Insecure` | `[runners.cache.s3] -> Insecure` | `--cache-s3-insecure` | `$CACHE_S3_INSECURE` | `[runners.cache] -> Insecure` | | `$S3_INSECURE` | 667| `GCS.AccessID` | `[runners.cache.gcs] -> AccessID` | `--cache-gcs-access-id` | `$CACHE_GCS_ACCESS_ID` | | | | 668| `GCS.PrivateKey` | `[runners.cache.gcs] -> PrivateKey` | `--cache-gcs-private-key` | `$CACHE_GCS_PRIVATE_KEY` | | | | 669| `GCS.CredentialsFile` | `[runners.cache.gcs] -> CredentialsFile` | `--cache-gcs-credentials-file` | `$GOOGLE_APPLICATION_CREDENTIALS` | | | | 670| `GCS.BucketName` | `[runners.cache.gcs] -> BucketName` | `--cache-gcs-bucket-name` | `$CACHE_GCS_BUCKET_NAME` | | | | 671| `Azure.AccountName` | `[runners.cache.azure] -> AccountName` | `--cache-azure-account-name` | `$CACHE_AZURE_ACCOUNT_NAME` | | | | 672| `Azure.AccountKey` | `[runners.cache.azure] -> AccountKey` | `--cache-azure-account-key` | `$CACHE_AZURE_ACCOUNT_KEY` | | | | 673| `Azure.ContainerName` | `[runners.cache.azure] -> ContainerName` | `--cache-azure-container-name` | `$CACHE_AZURE_CONTAINER_NAME` | | | | 674| `Azure.StorageDomain` | `[runners.cache.azure] -> StorageDomain` | `--cache-azure-storage-domain` | `$CACHE_AZURE_STORAGE_DOMAIN` | | | | 675 676### The `[runners.cache.s3]` section 677 678The following parameters define S3 storage for cache. 679 680In GitLab Runner 11.2 and earlier, these settings were in the global `[runners.cache]` section. 681 682| Parameter | Type | Description | 683|------------------|------------------|-------------| 684| `ServerAddress` | string | A `host:port` for the S3-compatible server. If you are using a server other than AWS, consult the storage product documentation to determine the correct address. For DigitalOcean, the address must be in the format `spacename.region.digitaloceanspaces.com`. | 685| `AccessKey` | string | The access key specified for your S3 instance. | 686| `SecretKey` | string | The secret key specified for your S3 instance. | 687| `BucketName` | string | Name of the storage bucket where cache is stored. | 688| `BucketLocation` | string | Name of S3 region. | 689| `Insecure` | boolean | Set to `true` if the S3 service is available by `HTTP`. Default is `false`. | 690 691Example: 692 693```toml 694[runners.cache] 695 Type = "s3" 696 Path = "path/to/prefix" 697 Shared = false 698 [runners.cache.s3] 699 ServerAddress = "s3.amazonaws.com" 700 AccessKey = "AWS_S3_ACCESS_KEY" 701 SecretKey = "AWS_S3_SECRET_KEY" 702 BucketName = "runners-cache" 703 BucketLocation = "eu-west-1" 704 Insecure = false 705``` 706 707For Amazon S3, the `ServerAddress` should always be `s3.amazonaws.com`. The MinIO S3 client 708gets bucket metadata and modifies the URL to point to the valid region, for example `s3-eu-west-1.amazonaws.com`. 709 710If `ServerAddress`, `AccessKey` or `SecretKey` aren't specified, then the S3 client uses the 711IAM instance profile available to the `gitlab-runner` instance. In an 712[autoscale](autoscale.md) configuration, this is not the on-demand machine 713that jobs are executed on. 714 715### The `[runners.cache.gcs]` section 716 717> Introduced in GitLab Runner 11.3.0. 718 719The following parameters define native support for Google Cloud Storage. To view 720where these values come from, view the 721[Google Cloud Storage (GCS) Authentication documentation](https://cloud.google.com/storage/docs/authentication#service_accounts). 722 723| Parameter | Type | Description | 724|-------------------|------------------|-------------| 725| `CredentialsFile` | string | Path to the Google JSON key file. Only the `service_account` type is supported. If configured, this value takes precedence over the `AccessID` and `PrivateKey` configured directly in `config.toml`. | 726| `AccessID` | string | ID of GCP Service Account used to access the storage. | 727| `PrivateKey` | string | Private key used to sign GCS requests. | 728| `BucketName` | string | Name of the storage bucket where cache is stored. | 729 730Examples: 731 732**Credentials configured directly in `config.toml` file:** 733 734```toml 735[runners.cache] 736 Type = "gcs" 737 Path = "path/to/prefix" 738 Shared = false 739 [runners.cache.gcs] 740 AccessID = "cache-access-account@test-project-123456.iam.gserviceaccount.com" 741 PrivateKey = "-----BEGIN PRIVATE KEY-----\nXXXXXX\n-----END PRIVATE KEY-----\n" 742 BucketName = "runners-cache" 743``` 744 745**Credentials in JSON file downloaded from GCP:** 746 747```toml 748[runners.cache] 749 Type = "gcs" 750 Path = "path/to/prefix" 751 Shared = false 752 [runners.cache.gcs] 753 CredentialsFile = "/etc/gitlab-runner/service-account.json" 754 BucketName = "runners-cache" 755``` 756 757### The `[runners.cache.azure]` section 758 759> Introduced in GitLab Runner 13.4.0. 760 761The following parameters define native support for Azure Blob Storage. To learn more, view the 762[Azure Blob Storage documentation](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction). 763While S3 and GCS use the word `bucket` for a collection of objects, Azure uses the word 764`container` to denote a collection of blobs. 765 766| Parameter | Type | Description | 767|-------------------|------------------|-------------| 768| `AccountName` | string | Name of the Azure Blob Storage account used to access the storage. | 769| `AccountKey` | string | Storage account access key used to access the container. | 770| `ContainerName` | string | Name of the [storage container](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction#containers) to save cache data in. | 771| `StorageDomain` | string | Domain name [used to service Azure storage endpoints](https://docs.microsoft.com/en-us/azure/china/resources-developer-guide#check-endpoints-in-azure) (optional). Default is `blob.core.windows.net`. | 772 773Example: 774 775```toml 776[runners.cache] 777 Type = "azure" 778 Path = "path/to/prefix" 779 Shared = false 780 [runners.cache.azure] 781 AccountName = "<AZURE STORAGE ACCOUNT NAME>" 782 AccountKey = "<AZURE STORAGE ACCOUNT KEY>" 783 ContainerName = "runners-cache" 784 StorageDomain = "blob.core.windows.net" 785``` 786 787## The `[runners.kubernetes]` section 788 789> Introduced in GitLab Runner v1.6.0. 790 791The following parameters define Kubernetes behavior. 792For more parameters, see the [Kubernetes executor documentation](../executors/kubernetes.md). 793 794| Parameter | Type | Description | 795|------------------|---------|-------------| 796| `host` | string | Optional. Kubernetes host URL. If not specified, the runner attempts to auto-discovery it. | 797| `cert_file` | string | Optional. Kubernetes auth certificate. | 798| `key_file` | string | Optional. Kubernetes auth private key. | 799| `ca_file` | string | Optional. Kubernetes auth ca certificate. | 800| `image` | string | Default Docker image to use for jobs when none is specified. | 801| `namespace` | string | Namespace to run Kubernetes jobs in. | 802| `privileged` | boolean | Run all containers with the privileged flag enabled. | 803| `allow_privilege_escalation` | boolean | Optional. Runs all containers with the `allowPrivilegeEscalation` flag enabled. | 804| `node_selector` | table | A `table` of `key=value` pairs of `string=string`. Limits the creation of pods to Kubernetes nodes that match all the `key=value` pairs. | 805| `image_pull_secrets` | array | A list of secrets that are used to authenticate Docker image pulling. | 806 807Example: 808 809```toml 810[runners.kubernetes] 811 host = "https://45.67.34.123:4892" 812 cert_file = "/etc/ssl/kubernetes/api.crt" 813 key_file = "/etc/ssl/kubernetes/api.key" 814 ca_file = "/etc/ssl/kubernetes/ca.crt" 815 image = "golang:1.8" 816 privileged = true 817 allow_privilege_escalation = true 818 image_pull_secrets = ["docker-registry-credentials"] 819 [runners.kubernetes.node_selector] 820 gitlab = "true" 821``` 822 823## Helper image 824 825When you use `docker`, `docker+machine`, or `kubernetes` executors, GitLab Runner uses a specific container 826to handle Git, artifacts, and cache operations. This container is created from an image named `helper image`. 827 828The helper image is available for amd64, arm, arm64, and s390x architectures. It contains 829a `gitlab-runner-helper` binary, which is a special compilation of GitLab Runner binary. It contains only a subset 830of available commands, as well as Git, Git LFS, SSL certificates store. 831 832The helper image has two flavors: `alpine` and `ubuntu`. The `alpine` image is currently the default due to its small 833footprint but can have [DNS issues in some environments](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4129). 834Using `helper_image_flavor = "ubuntu"` will select the `ubuntu` flavor of the helper image. 835 836When GitLab Runner is installed from the DEB/RPM packages, images for the supported architectures are installed on the host. 837When the runner prepares to execute the job, if the image in the specified version (based on the runner's Git 838revision) is not found on Docker Engine, it is automatically loaded. Both the 839`docker` and `docker+machine` executors work this way. 840 841The `kubernetes` executor and manual installations of GitLab Runner work differently. 842 843- For manual installations, the `gitlab-runner-helper` binary is not included. 844- For the `kubernetes` executor, the Kubernetes API doesn't allow the `gitlab-runner-helper` image to be loaded from a local archive. 845 846In both cases, GitLab Runner downloads the helper image from Docker Hub, from the official GitLab repository `gitlab/gitlab-runner-helper`. 847The GitLab Runner revision and architecture define which tag to download. 848 849### Default registry 850 851The helper image is pulled from a specific registry location, based on your version of GitLab 852Runner and the `FF_GITLAB_REGISTRY_HELPER_IMAGE` [feature flag](feature-flags.md). 853 854In 14.0, `FF_GITLAB_REGISTRY_HELPER_IMAGE=true` [became the default](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/27218) 855and helper images are pulled from GitLab Registry unless this feature flag is 856disabled. 857 858In 13.7, `FF_GITLAB_REGISTRY_HELPER_IMAGE` 859was [introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/27196) 860but disabled by default. 861 862Prior to 13.7, the helper image was always pulled from 863[Docker Hub](https://hub.docker.com/r/gitlab/gitlab-runner-helper). 864 865This feature flag can be disabled for: 866 867- A [specific pipeline](feature-flags.md#enable-feature-flag-in-pipeline-configuration). 868- [Every job](feature-flags.md#enable-feature-flag-in-runner-environment-variables). 869- If you are a runner administrator and don't want users to override it, you can set this 870 feature flag by specifying 871 [`[runners.feature_flags]`](feature-flags.md#enable-feature-flag-in-runner-configuration). 872 873### Override the helper image 874 875In some cases, you may need to override the helper image. There are many reasons for doing this: 876 8771. **To speed up jobs execution**: In environments with slower internet connection, downloading the 878 same image multiple times from Docker Hub can increase the time it takes to execute a job. Downloading the helper image from 879 a local registry, where the exact copy of `gitlab/gitlab-runner-helper:XYZ` is stored, can speed things up. 880 8811. **Security concerns**: You may not want to download external dependencies that were not checked before. There 882 might be a business rule to use only dependencies that were reviewed and stored in local repositories. 883 8841. **Build environments without internet access**: In some cases, jobs are executed in an environment that has 885 a dedicated, closed network. This doesn't apply to the `kubernetes` executor, where the image still needs to be downloaded 886 from an external registry that is available to the Kubernetes cluster. 887 8881. **Additional software**: You may want to install some additional software to the helper image, like 889 `openssh` to support submodules accessible with `git+ssh` instead of `git+http`. 890 891In these cases, you can configure a custom image by using the `helper_image` configuration field, 892which is available for the `docker`, `docker+machine`, and `kubernetes` executors: 893 894```toml 895[[runners]] 896 (...) 897 executor = "docker" 898 [runners.docker] 899 (...) 900 helper_image = "my.registry.local/gitlab/gitlab-runner-helper:tag" 901``` 902 903The version of the helper image should be considered to be strictly coupled with the version of GitLab Runner. 904One of the main reasons for providing these images is that GitLab Runner is using the 905`gitlab-runner-helper` binary. This binary is compiled from part of the GitLab Runner source. This binary uses an internal 906API that is expected to be the same in both binaries. 907 908By default, GitLab Runner references a `gitlab/gitlab-runner-helper:XYZ` image, where `XYZ` is based 909on the GitLab Runner architecture and Git revision. In GitLab Runner 11.3 and later, you can define the 910image version by using one of the 911[version variables](https://gitlab.com/gitlab-org/gitlab-runner/blob/11-3-stable/common/version.go#L48-50): 912 913```toml 914[[runners]] 915 (...) 916 executor = "docker" 917 [runners.docker] 918 (...) 919 helper_image = "my.registry.local/gitlab/gitlab-runner-helper:x86_64-${CI_RUNNER_REVISION}" 920``` 921 922With this configuration, GitLab Runner instructs the executor to use the image in version `x86_64-${CI_RUNNER_REVISION}`, 923which is based on its compilation data. After updating GitLab Runner to a new version, GitLab 924Runner tries to download the proper image. The image should be uploaded to the registry 925before upgrading GitLab Runner, otherwise the jobs start failing with a "No such image" error. 926 927In GitLab Runner 13.2 and later, the helper image is tagged by 928`$CI_RUNNER_VERSION` in addition to `$CI_RUNNER_REVISION`. Both tags are 929valid and point to the same image. 930 931```toml 932[[runners]] 933 (...) 934 executor = "docker" 935 [runners.docker] 936 (...) 937 helper_image = "my.registry.local/gitlab/gitlab-runner-helper:x86_64-v${CI_RUNNER_VERSION}" 938``` 939 940#### When using PowerShell Core 941 942> [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/27252) in GitLab 13.9. 943 944An additional version of the helper image for Linux, 945which contains PowerShell Core, is published with the `gitlab/gitlab-runner-helper:XYZ-pwsh` tag. 946 947## The `[runners.custom_build_dir]` section 948 949> [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/1267) in GitLab Runner 11.10. 950 951This section defines [custom build directories](https://docs.gitlab.com/ee/ci/yaml/README.html#custom-build-directories) parameters. 952 953This feature, if not configured explicitly, is 954enabled by default for `kubernetes`, `docker`, `docker-ssh`, `docker+machine`, 955and `docker-ssh+machine` executors. For all other executors, it is disabled by default. 956 957This feature requires that `GIT_CLONE_PATH` is in a path defined 958in `runners.builds_dir`. To use the `builds_dir`, use the 959`$CI_BUILDS_DIR` variable. 960 961By default, this feature is enabled only for `docker` and `kubernetes` executors, 962because they provide a good way to separate resources. This feature can be 963explicitly enabled for any executor, but use caution when you use it 964with executors that share `builds_dir` and have `concurrent > 1`. 965 966| Parameter | Type | Description | 967|-----------|---------|-------------| 968| `enabled` | boolean | Allow user to define a custom build directory for a job. | 969 970Example: 971 972```toml 973[runners.custom_build_dir] 974 enabled = true 975``` 976 977## The `[runners.referees]` section 978 979> - [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/1545) in GitLab Runner 12.7. 980> - Requires [GitLab v12.6](https://about.gitlab.com/releases/2019/12/22/gitlab-12-6-released/) or later. 981 982Use GitLab Runner referees to pass extra job monitoring data to GitLab. Referees are workers in the Runner Manager that query and collect additional data related to a job. The results 983are uploaded to GitLab as job artifacts. 984 985### Use the Metrics Runner referee 986 987If the machine or container running the job exposes [Prometheus](https://prometheus.io) metrics, GitLab Runner can query the Prometheus server for the entirety of the job duration. After the metrics are received, they are uploaded as a job artifact that can be used for analysis later. 988 989Only the [`docker-machine` executor](../executors/docker_machine.md) supports the referee. 990 991### Configure the Metrics Runner Referee for GitLab Runner 992 993Define `[runner.referees]` and `[runner.referees.metrics]` in your `config.toml` file within a `[[runner]]` section and add the following fields: 994 995| Setting | Description | 996| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | 997| `prometheus_address` | The server that collects metrics from GitLab Runner instances. It must be accessible by the Runner Manager when the job finishes. | 998| `query_interval` | The frequency the Prometheus instance associated with a job is queried for time series data, defined as an interval (in seconds). | 999| `queries` | An array of [PromQL](https://prometheus.io/docs/prometheus/latest/querying/basics/) queries that are executed for each interval. | 1000 1001Here is a complete configuration example for `node_exporter` metrics: 1002 1003```toml 1004[[runners]] 1005 [runners.referees] 1006 [runners.referees.metrics] 1007 prometheus_address = "http://localhost:9090" 1008 query_interval = 10 1009 metric_queries = [ 1010 "arp_entries:rate(node_arp_entries{{selector}}[{interval}])", 1011 "context_switches:rate(node_context_switches_total{{selector}}[{interval}])", 1012 "cpu_seconds:rate(node_cpu_seconds_total{{selector}}[{interval}])", 1013 "disk_read_bytes:rate(node_disk_read_bytes_total{{selector}}[{interval}])", 1014 "disk_written_bytes:rate(node_disk_written_bytes_total{{selector}}[{interval}])", 1015 "memory_bytes:rate(node_memory_MemTotal_bytes{{selector}}[{interval}])", 1016 "memory_swap_bytes:rate(node_memory_SwapTotal_bytes{{selector}}[{interval}])", 1017 "network_tcp_active_opens:rate(node_netstat_Tcp_ActiveOpens{{selector}}[{interval}])", 1018 "network_tcp_passive_opens:rate(node_netstat_Tcp_PassiveOpens{{selector}}[{interval}])", 1019 "network_receive_bytes:rate(node_network_receive_bytes_total{{selector}}[{interval}])", 1020 "network_receive_drops:rate(node_network_receive_drop_total{{selector}}[{interval}])", 1021 "network_receive_errors:rate(node_network_receive_errs_total{{selector}}[{interval}])", 1022 "network_receive_packets:rate(node_network_receive_packets_total{{selector}}[{interval}])", 1023 "network_transmit_bytes:rate(node_network_transmit_bytes_total{{selector}}[{interval}])", 1024 "network_transmit_drops:rate(node_network_transmit_drop_total{{selector}}[{interval}])", 1025 "network_transmit_errors:rate(node_network_transmit_errs_total{{selector}}[{interval}])", 1026 "network_transmit_packets:rate(node_network_transmit_packets_total{{selector}}[{interval}])" 1027 ] 1028``` 1029 1030Metrics queries are in `canonical_name:query_string` format. The query string supports two variables that are replaced during execution: 1031 1032| Setting | Description | 1033| ------------ | ----------------------------------------------------------------------------------------------------------------------------- | 1034| `{selector}` | Replaced with a `label_name=label_value` pair that selects metrics generated in Prometheus by a specific GitLab Runner instance. | 1035| `{interval}` | Replaced with the `query_interval` parameter from the `[runners.referees.metrics]` configuration for this referee. | 1036 1037For example, a shared GitLab Runner environment that uses the `docker-machine` executor would have a `{selector}` similar to `node=shared-runner-123`. 1038 1039## Deploy to multiple servers using GitLab CI/CD 1040 1041To deploy to multiple servers by using GitLab CI/CD, create a 1042single script that deploys to multiple servers, or create many scripts. 1043It depends on what you'd like to do. 1044