Docker

Provides hidden jobs for building and pushing Docker images. Used internally by the Docker pipeline.

Usage

include:
  - project: hosst/gitlab-pipelines
    file: helpers/docker.yaml

Variables

Variable	Default	Description
DOCKER_REGISTRY	$CI_REGISTRY	Registry to push to
DOCKER_REGISTRY_USER	$CI_REGISTRY_USER	Registry username
DOCKER_REGISTRY_PASSWORD	$CI_REGISTRY_PASSWORD	Registry password
DOCKER_FILE	Dockerfile	Path to the Dockerfile
DOCKER_BUILD_DIR	.	Build context directory
DOCKER_BUILD_TARGET		Single build target for multi-stage builds
DOCKER_IMAGE_NAME	$CI_PROJECT_PATH	Image name
DOCKER_IMAGE_VERSION	registry.gitlab.com/org/app:1.0	Tagged on git tag
DOCKER_IMAGE_VERSION_LATEST	registry.gitlab.com/org/app:latest	Latest for git tag
DOCKER_IMAGE_VERSION_BUILD	registry.gitlab.com/org/app:build	Build target for git tag
DOCKER_IMAGE_BRANCH	registry.gitlab.com/org/app/feature-xyz:7056b235	Branch commit
DOCKER_IMAGE_BRANCH_LATEST	registry.gitlab.com/org/app/feature-xyz:latest	Branch latest
DOCKER_IMAGE_BRANCH_BUILD	registry.gitlab.com/org/app/feature-xyz:build	Branch build target
DOCKER_IMAGE_BRANCH_DEFAULT_LATEST	registry.gitlab.com/org/app/main:latest	Default branch latest
DOCKER_IMAGE_BRANCH_DEFAULT_BUILD	registry.gitlab.com/org/app/main:build	Default branch build target

Base (.docker)

Base job that starts a Docker-in-Docker service, logs into the registry, and prints environment info.

Variables

Variable	Default	Description
DOCKER_HOST	tcp://docker:2375	Docker daemon host
DOCKER_TLS_CERTDIR	""	TLS directory (empty disables TLS)
DOCKER_DRIVER	overlay2	Storage driver

Examples

my-job:
  extends: .docker
  script:
    - docker ps

Build (.docker_build)

Extends .docker. Builds an image with docker build and pushes it. Runs on saas-linux-medium-amd64.

Variables

Variable	Default	Description
DOCKER_BUILD_COMMAND	docker build	Build command
DOCKER_BUILD_ARGS	--pull	Extra arguments passed to the build command
DOCKER_BUILD_CACHE_FROM	--cache-from $DOCKER_IMAGE_LATEST ...	Cache source arguments
DOCKER_BUILD_TAGS	--tag $DOCKER_IMAGE --tag $DOCKER_IMAGE_LATEST	Tag arguments
DOCKER_BUILD_EXTRA_ARGS		Additional arguments appended to the build command

Examples

build:
  extends: .docker_build
  stage: build

BuildX (.docker_buildx)

Extends .docker_build. Builds with docker buildx (BuildKit), enabling registry-backed layer caching. This is what the Docker pipeline uses.

Before building the final image, it iterates over DOCKER_BUILD_TARGETS and builds each named Dockerfile stage separately, pushing each one to the registry with its own :<target> tag (e.g. deps → :deps, build → :build). This makes intermediate stage images available as standalone images for later jobs in the same pipeline — for example, running tests inside the build stage image. Layer caching between pipeline runs is handled separately and efficiently by BuildKit's mode=max registry cache.

If DOCKER_BUILD_TARGETS is not set it falls back to DOCKER_BUILD_TARGET.

Variables

Variable	Default	Description
DOCKER_BUILD_COMMAND	docker buildx build	Build command (overrides .docker_build)
DOCKER_BUILD_ARGS	--progress=plain --pull --push	Build arguments (overrides .docker_build)
DOCKER_BUILD_CACHE_MODE	max	BuildKit cache mode (min or max)
DOCKER_BUILD_CACHE_FROM	--cache-from type=registry,ref=...	Cache source (overrides .docker_build)
DOCKER_BUILD_CACHE_TO	--cache-to type=registry,ref=...,mode=$DOCKER_BUILD_CACHE_MODE	Cache destination
DOCKER_BUILD_TARGETS		Space-separated list of Dockerfile stage names to build and push before the final image

Examples

The workflow block selects the right image tag variables based on whether the pipeline runs on a branch or a git tag. The job itself just extends .docker_buildx.

workflow:
  rules:
    - if: $CI_COMMIT_TAG
      variables:
        DOCKER_IMAGE: $DOCKER_IMAGE_VERSION
        DOCKER_IMAGE_LATEST: $DOCKER_IMAGE_VERSION_LATEST
        DOCKER_IMAGE_BUILD: $DOCKER_IMAGE_VERSION_BUILD
    - when: always
      variables:
        DOCKER_IMAGE: $DOCKER_IMAGE_BRANCH
        DOCKER_IMAGE_LATEST: $DOCKER_IMAGE_BRANCH_LATEST
        DOCKER_IMAGE_BUILD: $DOCKER_IMAGE_BRANCH_BUILD

docker:image:
  extends: .docker_buildx
  timeout: 1h

To pre-build intermediate stages, set DOCKER_BUILD_TARGET to the registry tag name and DOCKER_BUILD_TARGETS to the Dockerfile stages to push. Given this Dockerfile:

FROM node:20 AS deps
RUN npm ci

FROM deps AS build
RUN npm run build

FROM nginx AS final
COPY --from=build /app/dist /usr/share/nginx/html

The pipeline config below builds and pushes deps and build stages as separate images so later jobs can use them directly:

docker:image:
  extends: .docker_buildx
  timeout: 1h
  variables:
    DOCKER_BUILD_TARGETS: deps build
    # pushes registry/project/branch:deps and registry/project/branch:build
    # then builds and pushes the final image tagged :latest and :<sha>

test:
  stage: test
  image: registry.gitlab.com/$CI_PROJECT_PATH/$CI_COMMIT_REF_SLUG:build
  script:
    - npm test