Docker executor | GitLab Docs
/ Docker executor Tier : Free, Premium, Ultimate Offering : GitLab.com, GitLab Self-Managed, GitLab Dedicated GitLab Runner uses the Docker executor to run jobs on Docker images. You can use the Docker executor to: Maintain the same build environment for each job. Use the same image to test commands locally without the requirement of running a job in the CI server. The Docker executor uses Docker Engine to run each job in a separate and isolated container.
To connect to Docker Engine, the executor uses: The image and services you define in .gitlab-ci.yml . The configurations you define in config.toml . You can’t register a runner and its Docker executor without defining a default image in config.toml . The image defined in config.toml can be used when none is defined in .gitlab-ci.yml . If an image is defined in .gitlab-ci.yml , it overrides the one defined in config.toml .
Prerequisites: Install Docker . Docker executor workflow The Docker executor uses a Docker image based on Alpine Linux that contains the tools to run the prepare, pre-job, and post-job steps. To view the definition of the special Docker image, see the GitLab Runner repository . The Docker executor divides the job into several steps: Prepare : Creates and starts the services . Pre-job : Clones, restores cache , and downloads artifacts from previous stages.
Runs on a special Docker image. Job : Runs your build in the Docker image you configure for the runner. Post-job : Create cache, upload artifacts to GitLab. Runs on a special Docker Image. Supported configurations The Docker executor supports the following configurations. For known issues and additional requirements of Windows configurations, see Use Windows containers . Runner is installed on: Executor is: Container is running: Windows docker-windows Windows Windows docker Linux Linux docker Linux macOS docker Linux These configurations are not supported: Runner is installed on: Executor is: Container is running: Linux docker-windows Linux Linux docker Windows Linux docker-windows Windows Windows docker Windows Windows docker-windows Linux GitLab Runner uses Docker Engine API v1.25 to talk to the Docker Engine.
This means the minimum supported version of Docker on a Linux server is 1.13.0 . On Windows Server, it needs to be more recent to identify the Windows Server version. Use the Docker executor To use the Docker executor, manually define Docker as the executor in config.toml or use the gitlab-runner register --executor "docker" command to automatically define it. The following sample configuration shows Docker defined as the executor.
For more information about these values, see Advanced configuration toml concurrent = 4 [[ runners ]] name = "myRunner" url = "https://gitlab.com/ci" token = "......" executor = "docker" [ runners . docker ] tls_verify = true image = "my.registry.tld:5000/alpine:latest" privileged = false disable_entrypoint_overwrite = false oom_kill_disable = false disable_cache = false volumes = [ "/cache" , ] shm_size = 0 allowed_pull_policies = [ "always" , "if-not-present" ] allowed_images = [ "my.registry.tld:5000/*:*" ] allowed_services = [ "my.registry.tld:5000/*:*" ] [ runners . docker . volume_driver_ops ] "size" = "50G" Configure images and services Prerequisites: The image where your job runs must have a working shell in its operating system PATH .
Supported shells are: For Linux: sh bash PowerShell Core ( pwsh ). Introduced in 13.9 . For Windows: PowerShell ( powershell ) PowerShell Core ( pwsh ). Introduced in 13.6 . To configure the Docker executor, you define the Docker images and services in .gitlab-ci.yml and config.toml . Use the following keywords: image : The name of the Docker image that the runner uses to run jobs. Enter an image from the local Docker Engine, or any image in Docker Hub.
For more information, see the Docker documentation . To define the image version, use a colon ( : ) to add a tag. If you don’t specify a tag, Docker uses latest as the version. services : The additional image that creates another container and links to the image . For more information about types of services, see Services . Define images and services in .gitlab-ci.yml Define an image that the runner uses for all jobs and a list of services to use during build time.
Example: yaml image : ruby:3.3 services : - postgres:9.3 before_script : - bundle install test : script : - bundle exec rake spec To define different images and services per job: yaml before_script : - bundle install test:3.3 : image : ruby:3.3 services : - postgres:9.3 script : - bundle exec rake spec test:3.4 : image : ruby:3.4 services : - postgres:9.4 script : - bundle exec rake spec If you don’t define an image in .gitlab-ci.yml , the runner uses the image defined in config.toml .
Define images and services in config.toml To add images and services to all jobs run by a runner, update [runners.docker] in the config.toml . By default, the Docker executer uses the image defined in .gitlab-ci.yml . If you don’t define one in .gitlab-ci.yml , the runner uses the image defined in config.toml . Example: toml [ runners . docker ] image = "ruby:3.3" [[ runners . docker . services ]] name = "mysql:latest" alias = "db" [[ runners . docker . services ]] name = "redis:latest" alias = "cache" This example uses the array of tables syntax .
Define an image from a private registry Prerequisites: To access images from a private registry, you must authenticate GitLab Runner . To define an image from a private registry, provide the registry name and the image in .gitlab-ci.yml . Example: yaml image : my.registry.tld:5000/namespace/image:tag In this example, GitLab Runner searches the registry my.registry.tld:5000 for the image namespace/image:tag . Network configurations You must configure a network to connect services to a CI/CD job.
To configure a network, you can either: Recommended. Configure the runner to create a network for each job. Define container links. Container links are a legacy feature of Docker. Create a network for each job You can configure the runner to create a network for each job. When you enable this networking mode, the runner creates and uses a user-defined Docker bridge network for each job. Docker environment variables are not shared across the containers.
For more information about user-defined bridge networks, see the Docker documentation . To use this networking mode, enable FF_NETWORK_PER_BUILD in either the feature flag or the environment variable in the config.toml . Do not set the network_mode . Example: toml [[ runners ]] ( ... ) executor = "docker" environment = [ "FF_NETWORK_PER_BUILD=1" ] Or: toml [[ runners ]] ( ... ) executor = "docker" [ runners . feature_flags ] FF_NETWORK_PER_BUILD = true To set the default Docker address pool, use default-address-pool in dockerd .
If CIDR ranges are already used in the network, Docker networks may conflict with other networks on the host, including other Docker networks. This feature works only when the Docker daemon is configured with IPv6 enabled. To enable IPv6 support, set enable_ipv6 to true in the Docker configuration. For more information, see the Docker documentation . The runner uses the build alias to resolve the job container. DNS might not work correctly with a Docker-in-Docker ( dind ) service when you use this feature.
This behavior is due to an issue with Docker/Moby , where dind containers don’t inherit custom DNS entries when you specify a network. As a workaround, manually provide the custom DNS settings to the dind service. For example, if your custom DNS server is 1.1.1.1 , you can use 127.0.0.11 , which is Docker’s internal DNS service: yaml services : - name : docker:dind command : [ -- dns=127.0.0.11, --dns=1.1.1.1] This approach also allows containers to resolve services on the same network.
How the runner creates a network for each job When a job starts, the runner: Creates a bridge network, similar to the Docker command docker network create <n
The rest of this page is on the live site.