GitLab CI/CD Pipeline Orchestration with Docker Integration

The integration of Docker within GitLab CI/CD represents a fundamental shift in how modern software is built, tested, and deployed. By leveraging the .gitlab-ci.yml configuration file, developers can define an entire lifecycle of an application within a controlled, reproducible environment. This synergy allows for the abstraction of the build environment, ensuring that the "it works on my machine" problem is eradicated by encapsulating all dependencies, system libraries, and runtime configurations within a Docker image. The architecture typically involves a tripartite relationship between the GitLab Server, which manages the repositories and orchestration logic, the GitLab Runner, which executes the jobs, and the Docker Engine, which provides the containerization layer. When a developer pushes code to a branch, the GitLab Server parses the .gitlab-ci.yml file and instructs the Runner to pull a specific Docker image, instantiate a container, and execute a sequence of scripts. This process allows for extreme scalability, as multiple runners can operate across different hardware architectures or cloud providers, all while maintaining a consistent execution environment via Docker.

Docker Executor Configuration and Runner Registration

To achieve a fully containerized CI/CD workflow, the GitLab Runner must be configured to use the Docker executor. This executor is responsible for creating a fresh Docker container for every job, ensuring that each task starts from a clean slate and does not suffer from "environmental drift" caused by previous job remnants. The registration process is the critical first step in establishing this link.

The registration involves using the gitlab-runner register command, where specific flags define the behavior of the runner. For instance, the --executor "docker" flag tells the runner to use Docker to spawn job containers rather than executing scripts directly on the host machine's shell.

A sophisticated method of registration involves the use of a template configuration file, such as /tmp/test-config.template.toml. This allow for the pre-definition of services that should always be available to the runner. An example configuration for such a template is as follows:

toml [[runners]] [runners.docker] [[runners.docker.services]] name = "postgres:latest" [[runners.docker.services]] name = "mysql:latest"

When registering the runner with this template, the command would be:

bash sudo gitlab-runner register \ --url "https://gitlab.example.com/" \ --token "$RUNNER_TOKEN" \ --description "docker-ruby:2.6" \ --executor "docker" \ --template-config /tmp/test-config.template.toml \ --docker-image ruby:3.3

The impact of this configuration is that every job executed by this runner will have access to a ruby:3.3 environment and will have postgres:latest and mysql:latest containers running as sidecar services. This is vital for integration testing where the application requires a live database to verify data persistence and query logic.

Image Definition and Requirements within .gitlab-ci.yml

The image keyword in the .gitlab-ci.yml file is the primary mechanism for defining the execution environment. It specifies the Docker image that the Docker executor should pull from a registry—by default, Docker Hub—to run the CI/CD jobs.

The flexibility of the image keyword allows for global definitions or job-specific overrides. If defined at the top level of the .gitlab-ci.yml file, every job in the pipeline will use that image unless otherwise specified. However, for the Docker executor to function correctly, any image chosen must satisfy minimum technical requirements.

The mandatory applications that must be installed within the image include:

• sh
• bash (or orbash)
• grep

If these utilities are missing, the GitLab Runner will fail to execute the scripts because it cannot perform basic shell operations or parse job logs. From a contextual perspective, this means that ultra-minimal images (like some scratch or highly stripped-down alpine versions) may require the manual addition of these binaries via a custom Dockerfile before they can be used as a CI image.

Docker-in-Docker (DinD) and Service Orchestration

One of the most complex scenarios in GitLab CI is the requirement to build a Docker image inside a job that is already running inside a Docker container. This is achieved through the Docker-in-Docker (DinD) pattern.

To implement DinD, the .gitlab-ci.yml must define a service that provides the Docker daemon. A typical configuration looks like this:

yaml image: docker:18 services: - docker:18-dind variables: DOCKER_TLS_CERTDIR: "" DOCKER_HOST: tcp://docker:2375

In this setup, the docker:18 image provides the CLI tools, while the docker:18-dind service provides the actual engine. The DOCKER_HOST variable is critical because it tells the CLI where to find the daemon.

However, users often encounter errors when attempting to use docker compose. A common failure occurs when the command docker compose -f .gitlab/docker-compose-autotests.yml up results in an unknown shorthand flag: 'f' error. This typically happens when there is a mismatch between the installed Docker CLI version and the expected syntax of the Docker Compose V2 plugin (which is integrated into the docker command) versus the older standalone docker-compose binary.

To further optimize the performance of these services, registry mirrors can be implemented. This prevents the pipeline from hitting Docker Hub rate limits and increases pull speeds. This can be done in the .gitlab-ci.yml via the command attribute:

yaml services: - name: docker:24.0.5-dind command: ["--registry-mirror", "https://registry-mirror.example.com"]

Alternatively, this can be configured at the runner level in the config.toml file for both Docker and Kubernetes executors:

toml [[runners]] name = "kubernetes" [runners.kubernetes] privileged = true [[runners.kubernetes.services]] name = "docker:24.0.5-dind" command = ["--registry-mirror", "https://registry-mirror.example.com"]

The Shell Executor and Host-Level Docker Access

While the Docker executor is preferred for isolation, some scenarios require the Shell executor. This is often the case when the job needs direct access to the host machine's hardware or a pre-installed Docker Engine on the server.

The process for setting up a Shell executor involves several critical steps to ensure the gitlab-runner user has the necessary permissions to interact with the Docker socket.

The registration command for a shell executor is:

bash sudo gitlab-runner register -n \ --url "https://gitlab.com/" \ --registration-token REGISTRATION_TOKEN \ --executor shell \ --description "My Runner"

Once the runner is registered, the gitlab-runner user must be added to the docker group to avoid permission denied errors when executing docker commands:

bash sudo usermod -aG docker gitlab-runner

To verify that the setup is correct, the operator should test the access using the gitlab-runner user:

bash sudo -u gitlab-runner -H docker info

In the .gitlab-ci.yml file, this setup allows for simple Docker commands without the need for DinD services:

```yaml
default:
before_script:
- docker info

build_image:
script:
- docker build -t my-docker-image .
```

Advanced Image Building and Custom Runner Images

For organizations with complex requirements, using a standard public image is often insufficient. Building a custom GitLab Runner Docker image allows for the inclusion of specific tools like the AWS CLI or ECR Credential Helpers.

A custom image might be constructed by combining multiple stages, such as copying binaries from an aws-tools image into a base image containing jq, procps, curl, and unzip. The Dockerfile logic would include:

```dockerfile
RUN apt-get update && apt-get install -y \
jq procps curl unzip groff libgcrypt20 tar gzip less openssh-client \
&& apt-get clean && rm -rf /var/lib/apt/lists/*

COPY --from=aws-tools /usr/local/bin/ /usr/local/bin/
COPY --from=aws-tools /root/.docker/config.json /root/.docker/config.json
```

To automate the creation of this custom runner image, a .gitlab-ci.yml pipeline is used:

```yaml
variables:
DOCKERDRIVER: overlay2
IMAGENAME: $CIREGISTRYIMAGE:$CICOMMITREFNAME
GITLABRUNNERVERSION: v17.3.0
AWSCLI_VERSION: 2.17.36

stages:
- build

build-image:
stage: build
script:
- echo "Logging into GitLab container registry..."
- docker login -u $CIREGISTRYUSER -p $CIREGISTRYPASSWORD $CIREGISTRY
- echo "Building Docker image..."
- docker build --build-arg GITLABRUNNERVERSION=${GITLABRUNNERVERSION} --build-arg AWSCLIVERSION=${AWSCLIVERSION} -t ${IMAGENAME} .
```

This approach ensures that the build environment itself is version-controlled and reproducible, providing a "meta-layer" of CI/CD where the tools used to build the software are themselves managed by the pipeline.

Docker Compose Integration and File Path Logic

A frequent point of confusion for users is the interaction between the .gitlab-ci.yml and docker-compose.yml files, particularly when the compose file is stored outside the project repository on the runner server.

Consider a scenario where a user has a project structure with .gitlab-ci.yml and Dockerfile in the root, but the docker-compose.yml file is located at /data/YAML on the GitLab Runner server. The user may attempt the following:

yaml deploy: stage: deploy only: - main script: - cd /data/YAML - docker compose build --no-cache - docker compose up -d

The critical realization here is the distinction between the GitLab Server (where the code lives) and the GitLab Runner (where the code is executed). If the runner is using the Docker executor, the cd /data/YAML command will fail because the container's root filesystem is isolated from the host's /data/YAML directory. The container does not see the host's files unless they are explicitly mounted as volumes in the config.toml of the runner.

If the runner is using the Shell executor, however, this command would work because the script executes directly on the host's operating system. This highlights the fundamental difference in how file system access is handled between the two executors.

Comparison of GitLab Runner Executors for Docker Workflows

The following table provides a detailed comparison of the two primary executors used for Docker-based CI/CD pipelines.

Troubleshooting Common Docker CI Failures

When integrating Docker with GitLab CI, several common failures occur. Understanding these is key to maintaining a stable pipeline.

One major failure is the "Privileged Mode" error. For the docker:dind service to function, the runner must be configured with privileged = true in the config.toml file. Without this, the inner Docker daemon cannot start because it lacks the necessary kernel permissions to manage containers.

Another common issue is the DOCKER_TLS_CERTDIR variable. When using newer versions of the Docker image, TLS is enabled by default. If the user does not want to deal with certificates for a local or internal setup, setting DOCKER_TLS_CERTDIR: "" effectively disables TLS and allows the use of tcp://docker:2375.

Lastly, issues with docker compose flags often stem from the transition between the old docker-compose (Python-based) and the new docker compose (Go-plugin based). Users must ensure that the image they are using (e.g., docker:18 vs docker:24) contains the expected version of the Compose plugin.

Conclusion: Analysis of Docker-Centric CI/CD Architectures

The synthesis of GitLab CI/CD and Docker creates a powerful engine for software delivery, but it requires a precise understanding of the boundary between the orchestrator, the runner, and the container. The movement toward "Infrastructure as Code" is epitomized by the .gitlab-ci.yml file, which does not just define what to do, but where and how to do it.

The reliance on the Docker executor ensures that the pipeline is portable. By defining the image and services, a project can be moved from a self-managed GitLab instance to GitLab.com with minimal configuration changes, provided the runner's config.toml is aligned. The introduction of DinD allows for a complete build-and-push cycle, where the pipeline creates a production-ready image and pushes it to a registry, effectively closing the loop from source code to deployable artifact.

However, the "leaky abstraction" of Docker in CI/CD is most evident in the file system challenges. The attempt to access host-level directories like /data/YAML from within a containerized job fails without volume mounting, proving that the isolation provided by Docker is a double-edged sword. It provides security and consistency but introduces friction when interacting with legacy host-level configurations.

Ultimately, the most robust architecture for GitLab CI/CD involves:
1. Utilizing the Docker executor for maximum isolation.
2. Implementing a custom image containing all necessary CLI tools to reduce pipeline startup time.
3. Leveraging DinD with privileged mode for image building.
4. Using registry mirrors to ensure stability and bypass rate limits.
5. Strict versioning of both the Docker image and the GitLab Runner to avoid compatibility regressions.

Sources

1. Using the .gitlab-ci.yml file to access the docker-compose.yml file
2. Using Docker images in GitLab CI/CD
3. How to use docker compose in gitlab-ci
4. Using Docker build in GitLab CI/CD