The integration of Docker within GitLab CI/CD represents a fundamental shift in how modern software is delivered, moving away from static build servers toward a dynamic, ephemeral infrastructure. By leveraging containerization, developers can ensure that the environment where code is tested is identical to the environment where it is deployed, effectively eliminating the "it works on my machine" phenomenon. GitLab CI/CD facilitates this by allowing users to define the exact Docker image required for each job, ensuring a consistent, isolated, and scalable environment. This architectural approach allows for the automation of the entire lifecycle: from the initial build of a Docker image via a Dockerfile, through rigorous testing phases, and finally to the pushing of that image into a secure container registry for deployment.

Architectural Foundations of Docker in GitLab CI/CD

Continuous Integration and Continuous Delivery (CI/CD) is a methodological approach to software development that focuses on frequently delivering applications to customers by introducing automation into the development stages. The synergy between Docker and GitLab CI/CD provides three primary systemic benefits:

• Consistency: Docker ensures that the same environment is utilized across development, testing, and production, removing environmental discrepancies.
• Scalability: Applications can be scaled horizontally with ease, as containers are lightweight and can be instantiated rapidly.
• Isolation: Each container operates in isolation, which significantly reduces software conflicts and enhances the overall security posture of the pipeline.

For an organization to implement this, they must understand the different offerings and tiers available. These capabilities are accessible across Free, Premium, and Ultimate tiers, regardless of whether the instance is hosted on GitLab.com, is a GitLab Dedicated offering, or is a GitLab Self-Managed installation.

Configuring GitLab Runner for Docker Execution

To execute Docker commands within a CI/CD job, the underlying GitLab Runner must be specifically configured to support these operations. There are two primary paths for achieving this, depending on the security requirements and the level of access available on the host machine.

The Privileged Mode Requirement

The standard method for running Docker commands requires the runner to operate in privileged mode. This is necessary because the Docker daemon typically requires root-level access to manage containers and images. If an organization cannot enable privileged mode due to security policies, they must seek out a Docker alternative for building images.

Implementation via the Shell Executor

A viable alternative for enabling Docker commands is the use of the shell executor. In this configuration, the gitlab-runner user executes the commands directly on the host machine.

To set this up, the following sequence must be followed:

1. Install the GitLab Runner on the target server.
2. Register the runner using the shell executor. This is achieved via a command such as:
   sudo gitlab-runner register -n --url "https://gitlab.com/" --registration-token REGISTRATION_TOKEN --executor shell --description "My Runner"
3. Install the Docker Engine on the same server where the GitLab Runner is installed.

This configuration ensures that the gitlab-runner user has the necessary permissions to call the Docker binary and interact with the Docker daemon.

Docker Image Specifications and Job Definitions

Every job in a GitLab CI/CD pipeline that utilizes a Docker image must adhere to specific technical requirements to function correctly.

Mandatory Image Applications

Any image selected to run a CI/CD job must have the following software installed to avoid job failure:

• sh
• bash (or sh as a fallback)
• grep

Defining Images in the .gitlab-ci.yml File

The .gitlab-ci.yml file is the blueprint for the pipeline. Users can define a global image that applies to all jobs, as well as specific services that must run alongside the job.

The following example demonstrates a configuration using a Ruby image and a PostgreSQL service:

```yaml
default:
image: ruby:2.6
services:
- postgres:16.10
before_script:
- bundle install

test:
script:
- bundle exec rake spec
```

Image Naming Conventions

When specifying an image, GitLab supports three distinct formats to ensure the correct version of the software is pulled:

• Image Name Only: image: <image-name> (This defaults to the latest tag).
• Image with Tag: image: <image-name>:<tag> (Used for version pinning).
• Image with Digest: image: <image-name>@<digest> (Used for absolute immutability).

Advanced Configuration Options

Users can define images and services as either simple strings or as complex maps. A string must contain the full image name, including the registry path if the image is not hosted on Docker Hub. A map must contain at least the name option.

The following two configurations are functionally equivalent:

String-based approach:
yaml image: "registry.example.com/my/image:latest" services: - postgresql:16.10 - redis:latest

Map-based approach:
The map format allows for further extended configuration options beyond just the image name, providing more granular control over the container's behavior.

Authentication and Registry Management

Managing access to private images is critical for security and operational continuity. GitLab provides several mechanisms to handle authentication with container registries.

The GitLab Container Registry and CIJOBTOKEN

When utilizing the GitLab Container Registry on the same instance where the project is hosted, GitLab simplifies authentication by using the CI_JOB_TOKEN. This is a temporary token generated for the specific job.

For this to work, two conditions must be met:
- The user who triggers the job must hold a Developer, Maintainer, or Owner role for the project hosting the private image.
- The project hosting the private image must be configured to allow the other project to authenticate using the job token, as this access is disabled by default.

Credential Helpers and Third-Party Registries

For registries outside of GitLab (such as AWS ECR), credential helpers must be used. For example, when using <aws_account_id>.dkr.ecr.<region>.amazonaws.com, the docker-credential-ecr-login binary must be available in the GitLab Runner $PATH.

The runner manager acquires the AWS credentials and passes them to the runners. The configuration for these helpers is read by the runner process in a strict priority order:

1. config.json file located in /root/.docker.
2. The DOCKER_AUTH_CONFIG CI/CD variable.
3. The DOCKER_AUTH_CONFIG environment variable defined in the runner's config.toml file.
4. config.json file in the $HOME/.docker directory of the user running the process.

If the --user flag is used to run child processes as an unprivileged user, the home directory of the main runner process user is utilized.

Handling Multi-Registry Conflicts

A known limitation occurs when utilizing both private registries and public images from Docker Hub. If a credsStore is configured for all registries, the Docker daemon may attempt to use the private registry credentials for Docker Hub, causing the pull request to fail. To resolve this, the DOCKER_AUTH_CONFIG variable can be used to specify the configuration:

json { "credsStore": "osxkeychain" }

This JSON can be stored as a CI/CD variable or added to ${GITLAB_RUNNER_HOME}/.docker/config.json for self-managed runners.

Practical Implementation: Building and Pushing Images

Creating a functional pipeline involves the coordination of a Dockerfile and a .gitlab-ci.yml configuration.

Project Setup and Dockerfile Construction

To begin, a new project must be created in GitLab (e.g., DockerCIPipeline). A Dockerfile is then created in the root directory. For a Python application, a basic Dockerfile looks as follows:

```dockerfile

Use an official Python runtime as a parent image

FROM python:3.8-slim

Set the working directory

WORKDIR /app

Copy files into the container

COPY . .
```

Pipeline Configuration and Execution

The .gitlab-ci.yml file should be configured to use the GitLab Registry. Key environment variables provided by GitLab include:

• CI_REGISTRY_USER: The username of the user triggering the pipeline.
• CI_REGISTRY_PASSWORD: The access token used for authentication.

Once the files are created, they are pushed to the repository:

bash git add Dockerfile .gitlab-ci.yml git commit -m "Add Dockerfile and CI/CD pipeline configuration" git push origin main

Monitoring and Verification

After pushing the changes, the pipeline can be monitored via the GitLab interface:
- Navigate to CI/CD > Pipelines.
- Select the active pipeline to view real-time job logs.
- To verify the resulting image, navigate to Packages & Registries > Container Registry.

Operational Tooling and Commands

To manage and troubleshoot Docker within the CI/CD environment, the following commands are essential:

• docker build: This is used to create an image from a specified Dockerfile.
• docker images: This allows the user to list all Docker images currently stored on the system.
• docker ps: This provides a list of all currently running containers, which is useful for debugging service dependencies.

Extended CI/CD Use Cases and Community Examples

GitLab provides a wide array of examples to help users implement specific workflows. These range from official GitLab templates to community-contributed configurations.

Conclusion

The integration of Docker into GitLab CI/CD is not merely a convenience but a strategic necessity for achieving true continuous delivery. By utilizing the shell executor or privileged runners, organizations can automate the creation of immutable artifacts. The flexibility of the .gitlab-ci.yml file—allowing for specific images, services, and complex authentication via DOCKER_AUTH_CONFIG—ensures that the pipeline can adapt to any cloud environment, whether it be AWS ECR or the native GitLab Container Registry. The ability to monitor these pipelines and verify the resulting images in the Container Registry provides a transparent and auditable path from code commit to production deployment. Future advancements in this area include the exploration of multi-stage builds to reduce image size and the integration of more complex testing frameworks to ensure higher software quality before the image is pushed to the registry.

Sources

1. Using Docker to build Docker images
2. CI/CD examples
3. Using Docker images
4. Introduction to Docker integration in GitLab CI/CD pipelines