Docker

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

Usage

include:
  - project: hosstio/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_REPOSITORY	$CI_PROJECT_PATH	Registry path used as the base for all image tag variables
DOCKER_IMAGE_SUFFIX	""	Appended to every image tag; use to distinguish base image variants, e.g. -alpine or -bookworm
The image names, such as DOCKER_IMAGE_BRANCH, DOCKER_IMAGE_CACHE and DOCKER_IMAGE, come from the Docker pipeline. A project that uses these templates without that pipeline defines the names its jobs read; including the helper alone doesn't, so a pipeline that only runs containers doesn't look like it built an image to the Kubernetes deploys.

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 plus DOCKER_IMAGE_SUFFIX (e.g. deps → :deps, build → :build, or :build-alpine with the suffix -alpine), the tag DOCKER_IMAGE_BUILD names. 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_COMPRESSION	zstd	Layer compression for the image and the cache; set gzip when a cluster runs containerd older than 1.5
DOCKER_BUILD_ARGS	--progress=plain --pull --provenance=false --output type=image,push=true,oci-mediatypes=true,compression=$DOCKER_BUILD_COMPRESSION,force-compression=true	Build arguments (overrides .docker_build); --provenance=false pushes a plain single-platform manifest
DOCKER_BUILD_CACHE_MODE	max	BuildKit cache mode (min or max)
DOCKER_BUILD_CACHE_FROM	--cache-from type=registry,ref=$DOCKER_IMAGE_CACHE --cache-from type=registry,ref=$DOCKER_IMAGE_CACHE_DEFAULT	Cache sources: the branch cache, then the default branch cache (overrides .docker_build)
DOCKER_BUILD_CACHE_TO	--cache-to type=registry,ref=...,mode=$DOCKER_BUILD_CACHE_MODE,oci-mediatypes=true,compression=$DOCKER_BUILD_COMPRESSION,force-compression=true	Cache destination, compressed like the image so both share blobs
DOCKER_BUILD_ANNOTATIONS	--annotation org.opencontainers.image.revision=$CI_COMMIT_SHA --annotation org.opencontainers.image.source=$CI_PROJECT_URL	OCI annotations on the image manifest of the final image and each DOCKER_BUILD_TARGETS stage; set it to "" to push none
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
        DOCKER_IMAGE_CACHE: $DOCKER_IMAGE_CACHE_DEFAULT
    - 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

Image variants

To build multiple variants of the same image (e.g. different base images) in parallel, create one job per variant and set DOCKER_IMAGE_SUFFIX. The suffix is appended to every tag variable, including the cache, so each variant builds and caches independently.

docker:image:alpine:
  extends: docker:image
  variables:
    DOCKER_FILE: Dockerfile.alpine
    DOCKER_IMAGE_SUFFIX: "-alpine"

docker:image:bookworm:
  extends: docker:image
  variables:
    DOCKER_FILE: Dockerfile.bookworm
    DOCKER_IMAGE_SUFFIX: "-bookworm"

This produces tags like registry.gitlab.com/org/app/feature-xyz:abc1234-alpine and :abc1234-bookworm. The suffix must include the separator: "-alpine", not "alpine".