Lesson 08 intermediate

Building Docker Images in GitLab CI

Build and push container images from a pipeline: the GitLab container registry, Docker-in-Docker with TLS, tagging by commit and version, BuildKit layer caching through the registry, multi-arch images, daemonless alternatives after Kaniko was archived, services for integration tests and registry cleanup.

Orbit’s API ships as a container image. The pipeline should build that image once per commit, tag it so you always know what code is inside, push it to a registry and hand the exact tag to the deploy jobs. This lesson builds that, and explains the trade-offs between the ways to run docker build inside CI.

The Dockerfile

At the root of the Orbit repository:

FROM node:24-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev

FROM node:24-alpine
WORKDIR /app
ENV NODE_ENV=production
COPY --from=deps /app/node_modules ./node_modules
COPY dist/ ./dist/
USER node
EXPOSE 8080
CMD ["node", "dist/server.js"]

Two stages keep build tools out of the final image, USER node avoids running as root and copying package-lock.json before the source lets Docker reuse the dependency layer when only code changed. The Docker Tutorial covers these ideas in detail.

The GitLab container registry

Every GitLab project has a container registry, enabled by default on GitLab.com. GitLab gives every job what it needs to use it:

VariableValue
CI_REGISTRYRegistry host, registry.gitlab.com on GitLab.com
CI_REGISTRY_IMAGEBase image path for the project, e.g. registry.gitlab.com/orbit-team/orbit
CI_REGISTRY_USERA username valid for this job
CI_REGISTRY_PASSWORDA job-scoped password, valid only while the job runs

No personal tokens, no stored passwords. You will find pushed images under Deploy → Container registry.

Docker-in-Docker

The job’s container needs a Docker daemon to talk to. The usual answer on hosted runners is Docker-in-Docker (dind): a second container running dockerd, attached to the job as a service.

build-image:
  stage: package
  image: docker:29
  services:
    - docker:29-dind
  variables:
    DOCKER_TLS_CERTDIR: "/certs"
  needs: [build-api]
  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"

What each part does:

  • image: docker:29 provides the Docker CLI.
  • services: docker:29-dind starts a Docker daemon next to the job, reachable at the hostname docker.
  • DOCKER_TLS_CERTDIR: "/certs" makes the daemon and CLI share generated TLS certificates, so the connection is encrypted. Keep the CLI and daemon on the same major version.
  • needs: [build-api] downloads the dist/ artifact that the Dockerfile copies.
  • --password-stdin keeps the password out of the process list and the log.

dind needs a privileged container. GitLab’s hosted Linux runners allow it. On your own runners it means privileged = true in config.toml, which gives job containers broad power over the host. Use dedicated runners for image builds, or the daemonless options below.

Tagging strategy

A tag answers the question “what is inside this image?”. Use tags that never move for deployments and moving tags only for convenience:

TagExampleMoves?Use it for
Commit SHAorbit:3f9c2a1bNeverDeploys, rollbacks, tracing a bug to a commit
Versionorbit:1.4.0NeverReleases from Git tags
Branch slugorbit:feature-dark-modeEvery pushReview apps
latest / mainorbit:mainEvery mergeLocal testing only
build-image:
  # ...same as above...
  script:
    - docker build -t "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA" .
    - docker push "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA"
    - |
      if [ -n "$CI_COMMIT_TAG" ]; then
        docker tag "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA" "$CI_REGISTRY_IMAGE:$CI_COMMIT_TAG"
        docker push "$CI_REGISTRY_IMAGE:$CI_COMMIT_TAG"
      fi

Never deploy latest. A re-deploy of an old pipeline (lesson 7) must get the old image, and only a fixed tag guarantees that.

Add useful labels

Labels make an image explain itself. The OCI standard keys are understood by registries and scanners:

$ docker build \
    --label "org.opencontainers.image.revision=$CI_COMMIT_SHA" \
    --label "org.opencontainers.image.source=$CI_PROJECT_URL" \
    --label "org.opencontainers.image.created=$CI_PIPELINE_CREATED_AT" \
    -t "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA" .

Faster builds with a registry cache

Every dind job starts with an empty daemon, so Docker’s layer cache is gone and every build starts from zero. BuildKit can store its cache in the registry and pull it back next time:

build-image:
  stage: package
  image: docker:29
  services:
    - docker:29-dind
  variables:
    DOCKER_TLS_CERTDIR: "/certs"
    CACHE_REF: $CI_REGISTRY_IMAGE/cache:buildcache
  needs: [build-api]
  before_script:
    - echo "$CI_REGISTRY_PASSWORD" | docker login -u "$CI_REGISTRY_USER" --password-stdin "$CI_REGISTRY"
    - docker buildx create --use --driver docker-container
  script:
    - >
      docker buildx build
      --cache-from type=registry,ref=$CACHE_REF
      --cache-to type=registry,ref=$CACHE_REF,mode=max
      --tag "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA"
      --push .

mode=max caches the layers of every stage, including the deps stage, so an unchanged package-lock.json skips npm ci entirely. On a typical Node.js service this turns a three-minute build into thirty seconds.

Multi-architecture images

Graviton and other ARM machines are cheaper than x86 for many workloads. Buildx builds both in one go and pushes a single tag that works on either:

$ docker buildx build --platform linux/amd64,linux/arm64 \
    --tag "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA" --push .

Cross-building uses emulation and is slow for compiled languages. For heavy builds, run one job per architecture on native runners (for example saas-linux-small-arm64) and join the results with docker buildx imagetools create.

Building without a Docker daemon

You may not want privileged containers at all. Options that build images without dockerd:

ToolHow it worksNotes
BuildKit rootlessmoby/buildkit:rootless image runs buildctl-daemonless.shSame engine as docker buildx, no privileged mode on most runners
BuildahBuilds OCI images from a Dockerfile without a daemonCommon on Red Hat based platforms
KanikoWas the classic answerGoogle archived the project in 2025; community forks exist, but prefer an actively maintained tool for new pipelines

A rootless BuildKit job looks like this:

build-image-rootless:
  stage: package
  image:
    name: moby/buildkit:rootless
    entrypoint: [""]
  variables:
    BUILDKITD_FLAGS: --oci-worker-no-process-sandbox
  needs: [build-api]
  before_script:
    - mkdir -p ~/.docker
    - |
      AUTH=$(printf "%s:%s" "$CI_REGISTRY_USER" "$CI_REGISTRY_PASSWORD" | base64 | tr -d '\n')
      echo "{\"auths\":{\"$CI_REGISTRY\":{\"auth\":\"$AUTH\"}}}" > ~/.docker/config.json
  script:
    - >
      buildctl-daemonless.sh build
      --frontend dockerfile.v0
      --local context=.
      --local dockerfile=.
      --output type=image,name=$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA,push=true

Services for integration tests

The services keyword is not only for dind. Any image can run next to a job, which is perfect for testing against real dependencies:

integration-tests:
  stage: test
  image: node:24-alpine
  services:
    - name: postgres:17-alpine
      alias: db
    - name: redis:8-alpine
      alias: cache
  variables:
    POSTGRES_DB: orbit_test
    POSTGRES_USER: orbit
    POSTGRES_PASSWORD: orbit-test-only
    DATABASE_URL: postgres://orbit:orbit-test-only@db:5432/orbit_test
    REDIS_URL: redis://cache:6379
  script:
    - npm ci
    - npm run test:integration

The services are reachable under their alias. They are thrown away after the job, so tests always start from a clean database. Lesson 9 builds on this.

Keep the registry tidy

A busy project pushes hundreds of images a week. Turn on a cleanup policy under Settings → Packages and registries → Container registry: for example, keep the 20 most recent tags matching .*, always keep tags matching v\d+\.\d+\.\d+, and delete everything else older than 30 days. Production rollbacks need the release tags, not every commit from last year.

Exercise

Why should the deploy job use $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA rather than :latest?

  1. Because GitLab refuses to push a tag called latest
  2. Because latest images are always larger
  3. Because the SHA tag never changes, so a re-deploy of an old pipeline gets exactly the old image
  4. Because latest only works with Docker-in-Docker
Show answer

Answer: C. latest moves with every push, so the same deploy job could ship different code at different times. An immutable tag ties each deployment to one commit, which makes rollbacks and debugging reliable.

Exercise

Your dind builds take three minutes because npm ci runs from scratch every time. What helps most?

  1. Adding retry: 2 to the job
  2. Using buildx with –cache-from and –cache-to pointing at a registry cache
  3. Switching the job image to docker:latest
  4. Caching /var/lib/docker with the GitLab cache keyword
Show answer

Answer: B. Each dind job starts with an empty daemon, so local layers are lost. A registry cache lets BuildKit pull previous layers, so unchanged steps like npm ci are skipped.

Key takeaways

  • Every project has a container registry; CI jobs log in with job-scoped credentials.
  • Docker-in-Docker is simple but needs privileged containers; keep CLI and daemon versions matched and TLS on.
  • Deploy immutable tags (commit SHA, version), never latest.
  • BuildKit’s registry cache restores layers across jobs; buildx builds multi-arch images.
  • Rootless BuildKit or Buildah avoid privileged runners; Kaniko is archived.
  • services run databases and caches next to a job for integration tests.

FAQ

I get “Cannot connect to the Docker daemon at tcp://docker:2375”. Why?

The dind service is missing, the runner is not privileged, or the TLS settings do not match. With DOCKER_TLS_CERTDIR: "/certs" the client talks to port 2376 with TLS; make sure you did not also set DOCKER_HOST to port 2375.

Can I mount the runner’s Docker socket instead of using dind?

Yes, on your own runners, and it is fast because it shares the host’s layer cache. But every job then controls the host’s Docker, which equals root on that machine. Only do it on runners dedicated to one trusted project.

Should I push images to Docker Hub or a cloud registry instead?

Use whatever your runtime pulls from fastest and most securely. Many teams build into GitLab’s registry and copy release images to Amazon ECR or another cloud registry in the deploy stage. Lesson 11 pushes to ECR.

How do I scan the image for vulnerabilities?

Add GitLab’s container scanning after the build job. Lesson 10 covers it together with SAST, secret detection and dependency scanning.

Why does my image build pass locally but fail in CI?

Usually missing files: .dockerignore excludes something, or the dist/ artifact was not downloaded because the job does not need the build job. List the build context with ls -la in the job to check.

↑ ↓ navigate Enter open Esc close