GitLab CI with Docker - Commands & Configuration

Introduction

GitLab CI helps automate tasks like testing and deploying your code. Using Docker inside GitLab CI lets you run these tasks in clean, isolated containers, so your builds are consistent and easy to manage.

When you want to run your tests in a clean environment every time without installing software on your server.

When you need to build and package your application inside a container before deployment.

When you want to deploy your app using Docker images built automatically from your code.

When you want to share the same build environment with your team to avoid "it works on my machine" problems.

When you want to speed up your CI pipeline by using Docker caching and layers.

Config File - .gitlab-ci.yml

.gitlab-ci.yml

stages:
  - build
  - test

variables:
  DOCKER_DRIVER: overlay2

build_image:
  stage: build
  image: docker:24.0.5
  services:
    - docker:24.0.5-dind
  script:
    - docker info
    - docker build -t my-app-image .
    - docker images

test_image:
  stage: test
  image: my-app-image
  script:
    - echo "Running tests inside the Docker container"
    - ./run-tests.sh

stages: Defines the order of jobs: build first, then test.

variables: Sets Docker driver for better performance.

build_image job: Uses Docker official image and Docker-in-Docker service to build your app image.

test_image job: Runs tests inside the built Docker image to ensure your app works as expected.

Commands

Builds a Docker image named 'my-app-image' from the Dockerfile in the current directory. This image will be used later in the CI pipeline.

Terminal

docker build -t my-app-image .

Expected Output

Sending build context to Docker daemon  12.34MB

Step 1/5 : FROM python:3.11-slim

 ---> 123abc456def

Step 2/5 : COPY . /app

 ---> Using cache

Step 3/5 : WORKDIR /app

 ---> Using cache

Step 4/5 : RUN pip install -r requirements.txt

 ---> Using cache

Step 5/5 : CMD ["python", "app.py"]

 ---> Using cache

Successfully built abcdef123456

Successfully tagged my-app-image:latest

Lists all Docker images on the runner to verify that 'my-app-image' was built successfully.

Terminal

docker images

Expected Output

REPOSITORY      TAG       IMAGE ID       CREATED         SIZE

my-app-image    latest    abcdef123456   2 minutes ago   150MB

Runs the test script inside the built Docker image to check if the application works correctly.

Terminal

docker run --rm my-app-image ./run-tests.sh

Expected Output

Running tests...

All tests passed successfully!

→

--rm - Automatically remove the container after the test run to keep the environment clean

Key Concept

If you remember nothing else from this pattern, remember: use Docker-in-Docker in GitLab CI to build and test your app inside containers for consistent and clean pipelines.

Common Mistakes

Not enabling the Docker-in-Docker (dind) service in the GitLab CI job.

Without dind, Docker commands inside the CI job will fail because the Docker daemon is not available.

Add 'services: - docker:24.0.5-dind' to your job configuration to enable Docker daemon access.

Using the wrong Docker image that does not have Docker CLI installed for the build job.

Docker commands will fail if the image does not include the Docker client.

Use the official 'docker' image like 'docker:24.0.5' which includes the Docker CLI.

Trying to run tests outside the built Docker image instead of inside it.

Tests may fail due to missing dependencies or environment differences.

Run tests inside the Docker image you built to ensure the environment matches production.

Summary

Define stages and jobs in .gitlab-ci.yml to build and test Docker images.

Use Docker-in-Docker service to run Docker commands inside GitLab CI jobs.

Build your app image and run tests inside that image for consistent results.