The intersection of Continuous Integration (CI) and containerization represents a cornerstone of modern DevOps engineering. Within the GitLab ecosystem, the ability to automate the construction, testing, and distribution of Docker images provides a seamless path from source code to a deployable artifact. However, this integration is not a simple "plug-and-play" operation. Because GitLab CI/CD jobs are themselves typically executed within isolated Docker containers, a fundamental architectural challenge arises: how does a containerized process initiate the creation of another container? This technical paradox requires sophisticated orchestration strategies, ranging from the heavy-duty Docker-in-Docker (DinD) approach to the daemon-less elegance of Podman or the streamlined efficiency of multi-stage Dockerfiles.

The Architectural Paradox of Containerized CI Jobs

To understand the complexities of building Docker images within GitLab CI, one must first grasp the execution model of the GitLab Runner. When a developer pushes code to a repository, the GitLab Runner picks up the job and, in most modern configurations, spawns a Docker container to serve as the execution environment for that specific job.

The core issue is that the docker command-line interface (CLI) is merely a client. When a user executes docker build, the CLI does not perform the heavy lifting of image construction; instead, it communicates with a background process known as the Docker daemon (dockerd). In a standard local environment, dockerd runs as a persistent service on the host machine. In a GitLab CI environment, however, the job is trapped inside a container that lacks a resident Docker daemon. Without a daemon to receive instructions, the docker build command will fail, as it has no engine to command.

This creates a tiered requirement for infrastructure configuration, as the runner must be granted specific permissions or access to an external daemon to facilitate image construction.

Methodologies for Image Construction in GitLab CI

There are several distinct paths an engineer can take to resolve the daemon-less dilemma. The choice between these methods depends on the security requirements, the available runner infrastructure, and the desired level of simplicity.

Docker-in-Docker (DinD) Strategy

The most traditional and widely recognized method for overcoming the containerization barrier is the Docker-in-Docker (DinD) technique. This approach involves running a secondary Docker daemon inside the container that is executing the CI job.

To implement this, GitLab CI uses "services." In the GitLab CI configuration, a service is essentially a sidecar container that runs alongside the primary job container. By utilizing the docker:dind image as a service, the job container can communicate with this secondary daemon.

The configuration requires specific environment variables to bridge the communication gap between the client and the service. Specifically, the DOCKER_HOST variable must be set to point to the service's network address.

To successfully execute a DinD build, the .gitlab-ci.yml file must be structured to include the service and define the necessary connectivity:

yaml dind-build: services: - name: docker:dind alias: dockerdaemon variables: DOCKER_HOST: tcp://dockerdaemon:2375/ script: - docker build -t "$CI_REGISTRY_IMAGE:latest" . - docker push "$CI_REGISTRY_IMAGE:latest"

A critical constraint of the DinD method is the requirement for "privileged mode." For a Docker daemon to run inside a container, the host runner must be configured to allow privileged execution. This is a significant security consideration, as privileged containers have nearly all the capabilities of the host machine, potentially exposing the runner infrastructure to risks if the containerized process is compromised.

The Podman Alternative: A Daemon-less Approach

For organizations seeking to avoid the security implications of privileged mode, Podman offers a fundamentally different architectural paradigm. Unlike Docker, which relies on a centralized daemon, Podman is designed to be daemon-less. The Podman CLI performs the work directly, making it highly compatible with containerized CI environments that do not permit privileged access.

In a Podman-based workflow, the job container uses an image that contains the Podman binary (such as quay.io/podman/stable). Since there is no daemon to start or connect to, the complexity of the CI configuration is drastically reduced.

The implementation can be handled in two ways: using Podman natively or using a symbolic link to trick existing Docker-based scripts into using Podman.

Native Podman Execution

The following configuration demonstrates a clean, native Podman implementation where the CLI communicates directly with the container filesystem:

```yaml
stages:
- build

podman-build:
stage: build
image:
name: quay.io/podman/stable
script:
- podman login -u "$CIREGISTRYUSER" -p "$CIREGISTRYPASSWORD" "$CIREGISTRY"
- podman build -t "$CIREGISTRYIMAGE:podman" .
- podman push "$CIREGISTRY_IMAGE:podman"
```

In this model, the impact is immediate: the security surface is minimized because the job does not require root-level privileges on the host, and the configuration is simplified because there is no need to manage DOCKER_HOST or service aliases.

Podman as a Docker Drop-in Replacement

For legacy pipelines that are heavily invested in Docker syntax, Podman provides a bridge. By creating a symbolic link between the podman binary and the docker command, engineers can transition to Podman without rewriting their entire CI/CD YAML structure.

```yaml
stages:
- build

podman-build:
stage: build
image:
name: quay.io/podman/stable
script:
- ln -s /usr/bin/podman /usr/bin/docker
- docker login -u "$CIREGISTRYUSER" -p "$CIREGISTRYPASSWORD" "$CIREGISTRY"
- docker build -t "$CIREGISTRYIMAGE:podman" .
- docker push "$CIREGISTRY_IMAGE:podman"
```

This method allows for a gradual migration, providing the benefits of a daemon-less architecture while maintaining the command-line familiarity required by existing automation scripts.

The Shell Executor Method

An alternative to container-based builds is to use the GitLab Runner's "shell" executor. Instead of running the job inside a container, the runner executes commands directly on the host machine's shell (e.g., Bash or PowerShell).

This method is highly effective if the host machine already has the Docker Engine installed and configured. It removes the "container-in-container" problem entirely because the shell is running on the actual host where the Docker daemon resides.

To register a runner specifically for this purpose, the following command structure is utilized:

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

While the shell executor simplifies the build process by using the host's local Docker installation, it introduces a different set of responsibilities. The gitlab-runner user on the host machine must be granted explicit permissions to interact with the Docker daemon (typically via the docker group), and the host machine must be manually maintained with the necessary Docker Engine packages.

Multi-stage Dockerfiles: Streamlining the Build Process

A modern advancement in container engineering that significantly improves GitLab CI pipelines is the use of multi-stage Dockerfiles. Traditionally, a CI pipeline might require multiple distinct stages (e.g., a "build" stage to compile code and a "package" stage to create the image). Multi-stage builds consolidate these steps into a single docker build command.

By using multiple FROM instructions in a single Dockerfile, an engineer can separate the build environment from the production environment. This not only simplifies the .gitlab-ci.yml file but also results in much smaller, more secure production images.

Consider the following example of a Node.js application being containerized using multi-stage logic:

```dockerfile

Stage 1: The Builder

FROM node:8 as builder
WORKDIR /usr/src/app
COPY package.json .
RUN npm install
COPY ./src /usr/src/app/
RUN npm run build

Stage 2: The Production Image

FROM node:8-alpine
WORKDIR /usr/src/app
COPY package.json .
RUN npm install --production
COPY --from=builder /usr/src/app/dist /usr/src/app/dist
COPY --from=builder /usr/src/app/server.js /usr/src/app/server.js
CMD ["node", "server.js"]
```

In this workflow:
1. The builder stage performs the heavy lifting, including installing all dependencies and compiling the source code. These artifacts are stored in intermediate image layers.
2. The final stage starts from a lightweight node:8-alpine base image.
3. The COPY --from=builder command selectively pulls only the necessary compiled files from the first stage into the final image.

The impact of this approach is twofold: the CI pipeline becomes more robust because the complexity is encapsulated within the Dockerfile itself rather than scattered across the GitLab CI YAML, and the final deployment artifact is stripped of all build-time tools and unnecessary dependencies, reducing the attack surface and deployment latency.

Registry Integration and Image Lifecycle

Once an image is successfully built using any of the aforementioned methods, the final step in the CI/CD lifecycle is to push the image to a container registry. GitLab provides a built-in Container Registry that integrates seamlessly with its CI/CD variables.

Authentication and Pushing

The GitLab Runner provides predefined environment variables that allow for secure, automated authentication to the registry. These include $CI_REGISTRY_USER, $CI_REGISTRY_PASSWORD, and $CI_REGISTRY.

A typical workflow for building an image and pushing it to the GitLab registry involves three primary actions:
1. Authenticating via the CLI (Docker or Podman).
2. Tagging the image with the registry's full path.
3. Pushing the tagged image to the remote repository.

For a Python-based application, the commands might look like this:

bash docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" "$CI_REGISTRY" docker build -t "$CI_REGISTRY_IMAGE:py-3.8" . docker push "$CI_REGISTRY_IMAGE:py-3.8"

Verification and Deployment

After the image is pushed, it can be verified by pulling it from the registry in a separate environment or a subsequent CI job. This serves as a validation step to ensure the image was constructed correctly and is accessible to the intended deployment target.

To test a built image, an engineer can use the docker pull and docker run commands. For example, to verify a Python 3.8 image built for a specific project:

bash docker pull gitlab-registry.cern.ch/<user_name>/build-with-ci-example:py-3.8 docker run --rm -ti gitlab-registry.cern.ch/<user_name>/build-with-ci-example:py-3.8 python3 --version

This command sequence pulls the image, executes the python3 --version command within a transient container, and then removes the container once the command completes. If the output returns the expected version (e.g., Python 3.8.9), the image is confirmed as functional.

Comparative Analysis of Implementation Strategies

Selecting the appropriate method for building Docker images in GitLab CI requires a balanced evaluation of security, complexity, and infrastructure control.

The decision matrix typically points toward Podman for modern, security-conscious organizations, toward DinD for legacy environments where privileged runners are already established, and toward Multi-stage builds as a mandatory best practice regardless of the chosen execution engine.

Conclusion

The orchestration of Docker image construction within GitLab CI/CD is a multi-faceted engineering challenge that necessitates a deep understanding of both container architecture and CI/CD workflows. While the Docker-in-Docker (DinD) approach remains a pervasive standard, its reliance on privileged mode has paved the way for the rise of daemon-less alternatives like Podman, which offer a more secure and streamlined path for containerized builds. Furthermore, the adoption of multi-stage Dockerfiles represents a significant shift toward encapsulating build logic within the image definition itself, thereby reducing the operational overhead of the CI pipeline and producing highly optimized, production-ready artifacts.

Ultimately, the most efficient pipelines are those that leverage the right tool for the specific environmental constraints. By moving away from complex, multi-stage CI configurations and toward consolidated Dockerfiles and daemon-less engines, DevOps engineers can build more resilient, secure, and scalable containerized deployment workflows.

Sources

1. PythonSpeed: Building Docker images on GitLab CI
2. GitLab Documentation: Use Docker to build Docker images
3. Snorre.io: Building Docker images with GitLab CI
4. Matthew Feickert: Intro to Docker - Build with CI