Skip to content
Tutorials Center
My learning

Topics

Lesson 18 of 36 ยท Runners and Jobs

Docker Images and Services in Jobs

Use image and services in GitLab CI to test against databases, set entrypoints, build container images with Docker-in-Docker or Kaniko, and push to the registry.

With the Docker executor, the image keyword picks the environment your script runs in, and services start extra containers next to it. These two keywords cover most needs: "run my tests with Python 3.13 against a PostgreSQL database", or "build a container image of my app". This lesson shows how both work, including the tricky part, building images inside a job.

Choosing an image

YAML
tests:
  image: python:3.13-slim
  script:
    - python --version
    - pip install -r requirements.txt
    - pytest

Pick images that have what you need and little else: smaller images start faster. Pin the tag to a version (python:3.13-slim), not latest, so a surprise upgrade cannot break the pipeline. Images from Docker Hub work by default; private registries, including GitLab's own, need credentials, usually set in a DOCKER_AUTH_CONFIG CI/CD variable or by logging in. To change the image's startup command, use the long form:

YAML
tests:
  image:
    name: registry.example.com/team/tools:2.1
    entrypoint: [""]       # override an entrypoint that would swallow your script
  script:
    - ./run-checks.sh

Many tool images define an ENTRYPOINT that starts the tool itself. GitLab runs your script through a shell, so you usually need to clear the entrypoint as shown.

Services: containers next to your job

services start additional containers on a shared network before the script. The most common use is a database or cache for integration tests.

YAML
integration-tests:
  image: python:3.13-slim
  services:
    - name: postgres:16
      alias: db
  variables:
    POSTGRES_DB: shop
    POSTGRES_USER: runner
    POSTGRES_PASSWORD: example-only
    DATABASE_URL: "postgresql://runner:example-only@db:5432/shop"
  script:
    - pip install -r requirements.txt
    - pytest tests/integration

How it works:

  • The service container is reachable by its hostname. Without an alias, GitLab derives the hostname from the image name (for a simple image like postgres:16 it is postgres). An alias gives you an explicit, readable name (db).
  • Variables defined on the job are passed to service containers too, which is how POSTGRES_DB configures the database. Use throwaway values for such passwords.
  • Services start in parallel with each other, and GitLab waits for exposed ports to open before your script starts, but the application inside may still be initializing. A short retry loop in before_script avoids flaky first connections.
  • Service containers do not share your project files; they are separate.

The stand-in below models connection details, building the connection URL from a services list and the variables. It gives you a feel for how names tie together; it does not start any database.

Python Stand-in: service hostnames and connection URLs

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

For images with a registry path (like registry.example.com/team/postgres), the default hostname rules are more elaborate, so use an explicit alias there.

Building container images in a job

Building an image is hard inside a container: your job already runs in a container, and docker build needs a Docker daemon. There are three common solutions.

1. Docker-in-Docker (dind). Start a Docker daemon as a service and talk to it with the Docker CLI image.

YAML
build-image:
  image: docker:27
  services:
    - docker:27-dind
  variables:
    DOCKER_TLS_CERTDIR: "/certs"
  before_script:
    - echo "$CI_REGISTRY_PASSWORD" | docker login -u "$CI_REGISTRY_USER" --password-stdin "$CI_REGISTRY"
  script:
    - docker build -t "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA" .
    - docker push "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA"

The dind service requires the runner to be configured with privileged = true, which weakens isolation. GitLab's hosted Linux runners are set up for this. CI_REGISTRY, CI_REGISTRY_USER and CI_REGISTRY_PASSWORD are predefined variables for GitLab's container registry; the login uses a short-lived credential for the job.

2. Docker socket binding. Mount the host's /var/run/docker.sock into jobs and use the host daemon directly. It is fast and caches layers, but any job can control the host's Docker, which is effectively root. Use it only on trusted, dedicated runners.

3. Daemonless builders. Tools such as Kaniko or BuildKit in rootless mode build images without a Docker daemon and without privileged mode, which is safer. Kaniko's own project is now archived (maintained forks exist), so check the current recommendation in GitLab's documentation before choosing.

Whichever route you use, tag images with something unique per commit ($CI_COMMIT_SHORT_SHA) and optionally a moving tag (latest, or a version from $CI_COMMIT_TAG). The registry chapter later in the course shows how to store and clean them.

Image tag helper

The stand-in below builds the tags to push for a commit, following a common convention. It is a pure function you can adapt for your own scheme.

Python Stand-in: choose image tags for a build

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Practical tips

  • Cache layers: put rarely changing instructions (installing OS packages and dependencies) early in the Dockerfile, as covered in the Docker tutorial.
  • Avoid rate limits: pulling many images from Docker Hub in busy pipelines can hit limits; use a registry mirror or GitLab's dependency proxy.
  • Pin and scan: pin image versions and scan built images in the security stage.
  • Keep secrets out of images: pass them at runtime or through build secrets, never ARG or ENV in the Dockerfile.
  • Debug locally: run the same image with docker run -it --rm python:3.13-slim sh to reproduce a failing job.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How does a job container reach a service started with alias db?

    Service containers are reachable by their hostname or alias on the network the executor creates for the job.
  2. 2. Why is the dind service a security concern?

    Docker-in-Docker needs privileged mode, which weakens isolation between jobs and the host.
  3. 3. A tool image's entrypoint swallows your script. What do you do?

    The long form of image lets you clear or replace the entrypoint so your script runs in a shell.
  4. 4. Why pin image tags like python:3.13-slim instead of latest?

    A moving tag can change under you and break the pipeline without any change in your repository.

Summary

  • image chooses the job's environment; pin versions and override the entrypoint when needed.
  • services start database and cache containers reachable by hostname or alias.
  • Build images with Docker-in-Docker (privileged), a bound socket (trusted runners only) or a daemonless builder.
  • Tag images with the commit SHA plus meaningful moving tags.
  • Next you will see how pipelines deliver those images and artifacts to environments in the rest of the course.

Next: Environments and Deployments