GitLab CI template for Docker¶

This project implements a GitLab CI/CD template to build, check and inspect your containers with Docker.

Usage¶

This template can be used both as a CI/CD component or using the legacy include:project syntax.

Use as a CI/CD component¶

Add the following to your .gitlab-ci.yml:

include:
  # 1: include the component
  - component: $CI_SERVER_FQDN/to-be-continuous/docker/gitlab-ci-docker@5.13.3
    # 2: set/override component inputs
    inputs:
      build-tool: buildah # ⚠ this is only an example

Use as a CI/CD template (legacy)¶

Add the following to your .gitlab-ci.yml:

include:
  # 1: include the template
  - project: 'to-be-continuous/docker'
    ref: '5.13.3'
    file: '/templates/gitlab-ci-docker.yml'

variables:
  # 2: set/override template variables
  DOCKER_BUILD_TOOL: buildah # ⚠ this is only an example

Understanding the Docker template¶

The template supports following ways of building container images:

The former Docker-in-Docker (DinD) technique, that was widely used for years because of no other alternative, but that is now commonly recognized to have significant security issues (read this post for more info),
Or using kaniko, an open-source, daemonless tool from Google for building Docker images, and that solves Docker-in-Docker security issues (and also speeds-up build times).
Or using buildah, an open-source, daemonless tool backed by RedHat for building Docker images, and that solves Docker-in-Docker security issues (and also speeds-up build times), and can also be configured to run rootless.

By default, the template uses the kaniko way, but you may select an alternate build tool by using the DOCKER_BUILD_TOOL variable (see below).

If you choose to use 'Docker-in-Docker' option considering the associated security risks, make sure your runner has required privileges to run Docker-in-Docker (see GitLab doc).

Global variables¶

The Docker template uses some global configuration used throughout all jobs.

Input / Variable	Description	Default value
`build-tool` / `DOCKER_BUILD_TOOL`	The build tool to use for building container image, possible values are `kaniko`, `buildah` or `dind`	`kaniko`
`kaniko-image` / `DOCKER_KANIKO_IMAGE`	The image used to run `kaniko` - for kaniko build only	`gcr.io/kaniko-project/executor:debug` (use `debug` images for GitLab)
`buildah-image` / `DOCKER_BUILDAH_IMAGE`	The image used to run `buildah` - for buildah build only	`quay.io/buildah/stable`
`image` / `DOCKER_IMAGE`	The Docker image used to run the docker client (see full list) - for Docker-in-Docker build only	`registry.hub.docker.com/library/docker:latest`
`dind-image` / `DOCKER_DIND_IMAGE`	The Docker image used to run the Docker daemon (see full list) - for Docker-in-Docker build only	`registry.hub.docker.com/library/docker:dind`
`file` / `DOCKER_FILE`	The path to your `Dockerfile`	`Dockerfile`
`context-path` / `DOCKER_CONTEXT_PATH`	The Docker context path (working directory)	none only set if you want a context path different from the Dockerfile location

In addition to this, the template supports standard Linux proxy variables:

Input / Variable	Description	Default value
`http_proxy`	Proxy used for http requests	none
`https_proxy`	Proxy used for https requests	none
`no_proxy`	List of comma-separated hosts/host suffixes	none

Images¶

For each Dockerfile, the template builds an image that may be pushed as two distinct images, depending on a certain workflow:

snapshot: the image is first built from the Dockerfile and then pushed to some Docker registry as the snapshot image. It can be seen as the raw result of the build, but still untested and unreliable.
release: once the snapshot image has been thoroughly tested (both by package-test stage jobs and/or acceptance stage jobs after being deployed to some server), then the image is pushed one more time as the release image. This second push can be seen as the promotion of the snapshot image being now tested and reliable.

In practice:

the snapshot image is always pushed by the template (pipeline triggered by a Git tag or commit on any branch),
the release image is only pushed:
on a pipeline triggered by a Git tag,
on a pipeline triggered by a Git commit on master.

The snapshot and release images are defined by the following variables:

Input / Variable	Description	Default value
`snapshot-image` / `DOCKER_SNAPSHOT_IMAGE`	Docker snapshot image	`$CI_REGISTRY_IMAGE/snapshot:$CI_COMMIT_REF_SLUG`
`release-image` / `DOCKER_RELEASE_IMAGE`	Docker release image	`$CI_REGISTRY_IMAGE:$CI_COMMIT_REF_NAME`

As you can see, the Docker template is configured by default to use the GitLab container registry. You may perfectly override this and use another Docker registry, but be aware of a few things:

the DOCKER_SNAPSHOT_IMAGE requires a Docker registry that allows tag overwrite,
the DOCKER_RELEASE_IMAGE may use a Docker registry that doesn't allow tag overwrite, but:
you should avoid overwriting a Git tag (at it will obviously fail while trying to (re)push the Docker image),
you have to deactivate publish on main (or master) branch by setting the $DOCKER_PROD_PUBLISH_STRATEGY variable to none (as it would lead to the main tag being overwritten).

Registries and credentials¶

As seen in the previous chapter, the Docker template uses by default the GitLab registry to push snapshot and release images. Thus it makes use of credentials provided by GitLab itself to login (CI_REGISTRY_USER / CI_REGISTRY_PASSWORD).

But when using other registry(ies), you'll have also to configure appropriate Docker credentials.

Using the same registry for snapshot and release¶

If you use the same registry for both snapshot and release images, you shall use the following configuration

variables:

Input / Variable	Description
`DOCKER_REGISTRY_USER`	Docker registry username for image registry
`DOCKER_REGISTRY_PASSWORD`	Docker registry password for image registry

Using different registries for snapshot and release¶

If you use different registries for snapshot and release images, you shall use separate configuration variables:

Input / Variable	Description
`DOCKER_REGISTRY_SNAPSHOT_USER`	Docker registry username for snapshot image registry
`DOCKER_REGISTRY_SNAPSHOT_PASSWORD`	Docker registry password for snapshot image registry
`DOCKER_REGISTRY_RELEASE_USER`	Docker registry username for release image registry
`DOCKER_REGISTRY_RELEASE_PASSWORD`	Docker registry password for release image registry

Setting your own Docker configuration file (advanced)¶

There might be cases where you need to provide the complete Docker configuration file:

need to declare authentication credentials for other registries than the 2 predefined ones (snapshot & release),
need to declare a credentials store (ex: in order to publish to Amazon ECR with Kaniko for instance),
need to declare proxies,
...

If you are in one of those cases, you will need to use the DOCKER_CONFIG_FILE variable, expected to declare the path to your custom Docker configuration file (JSON). You may:

leave the default value (.docker/config.json) or override it to some alternate location in your project repository and create the file without any secret in it using our dynamic variables replacement (see below),
or override it as a GitLab project variable of type File, possibly inlining your secret credentials in it.

Input / Variable	Description	Default value
`config-file` / `DOCKER_CONFIG_FILE`	Path to the Docker configuration file (JSON)	`.docker/config.json`

Moreover, this file supports dynamic environment variables replacement. That means it may contain references to other environment variables (in the format ${variable_name}) that will be dynamically replaced by the template before evaluation. In addition to you own defined variables, you may use the following variables (provided and managed by the template):

${docker_snapshot_authent_token}: the authentication token required by the snapshot registry (computed from configured DOCKER_REGISTRY_SNAPSHOT_USER / DOCKER_REGISTRY_SNAPSHOT_PASSWORD variables)
${docker_snapshot_registry_host}: the snapshot registry host (based on the configured DOCKER_SNAPSHOT_IMAGE variable)
${docker_release_authent_token}: the authentication token required by the release registry (computed from configured DOCKER_REGISTRY_RELEASE_USER / DOCKER_REGISTRY_RELEASE_PASSWORD variables)
${docker_release_registry_host}: the release registry host (based on the configured DOCKER_RELEASE_IMAGE variable)

Example 1: Docker configuration file inlined in the project repository (.docker/config.json) with dynamic variables replacement:

{
  "auths": {
    "${docker_snapshot_registry_host}": {
      "auth": "${docker_release_authent_token}"
    },
    "${docker_release_registry_host}": {
      "auth": "${docker_snapshot_authent_token}"
    },
    "my-readonly-repo-to-pull": {
      "auth": "${MY_OWN_REGISTRY_TOKEN}"
    }
  }
}

This file uses:

template-managed ${docker_snapshot_authent_token}, ${docker_snapshot_registry_host}, ${docker_release_authent_token} and ${docker_release_registry_host} variables,
the user-defined ${MY_OWN_REGISTRY_TOKEN} ( an authentication token can be obtained with command echo "user:password" | base64 and then be stored as a masked GitLab CI/CD project variable).

Example 2: Docker configuration file declared as a GitLab project variable of type File with dynamic variables replacement:

{
  "auths": {
    "$${docker_snapshot_registry_host}": {
      "auth": "$${docker_release_authent_token}"
    },
    "$${docker_release_registry_host}": {
      "auth": "$${docker_snapshot_authent_token}"
    },
    "my-readonly-repo-to-pull": {
      "auth": "ZG9ja2VyZHVkZTpnb3RjaGEh"
    }
  }
}

This file uses:

template-managed ${docker_snapshot_authent_token}, ${docker_snapshot_registry_host}, ${docker_release_authent_token} and ${docker_release_registry_host} variables ( mind the double $$ to prevent GitLab from trying to evaluate the variable),
the user-defined authentication may be inlined as a GitLab project variable is a place safe enough to store secrets.

Multi Dockerfile support¶

This template supports building multiple Docker images from a single Git repository.

You can define the images to build using the parallel matrix jobs pattern inside the .docker-base job (this is the top parent job of all Docker template jobs).

Since each job in the template extends this base job, the pipeline will produce one job instance per image to build. You can independently configure each instance of these jobs by redefining the variables described throughout this documentation.

For example, if you want to build two Docker images, you must specify where the Dockerfiles are located and where the resulting images will be stored. You can do so by adding a patch to the .docker-base job in your .gitlab-ci.yml file so that it looks like this:

.docker-base:
  parallel:
    matrix:
      - DOCKER_FILE: "front/Dockerfile"
        DOCKER_SNAPSHOT_IMAGE: "$CI_REGISTRY_IMAGE/front:$CI_COMMIT_REF_SLUG"
        DOCKER_RELEASE_IMAGE: "$CI_REGISTRY_IMAGE/front:$CI_COMMIT_REF_NAME"
      - DOCKER_FILE: "back/Dockerfile"
        DOCKER_SNAPSHOT_IMAGE: "$CI_REGISTRY_IMAGE/back:$CI_COMMIT_REF_SLUG"
        DOCKER_RELEASE_IMAGE: "$CI_REGISTRY_IMAGE/back:$CI_COMMIT_REF_NAME"

If you need to redefine a variable with the same value for all your Dockerfiles, you can just declare this variable as a global variable. For example, if you want to build all your images using buildah, you can simply define the DOCKER_BUILD_TOOL variable as a global variable with value buildah:

variables:
  DOCKER_BUILD_TOOL: "buildah"

Secrets management¶

Here are some advices about your secrets (variables marked with a ):

Manage them as project or group CI/CD variables:
masked to prevent them from being inadvertently displayed in your job logs,
protected if you want to secure some secrets you don't want everyone in the project to have access to (for instance production secrets).
In case a secret contains characters that prevent it from being masked, simply define its value as the Base64 encoded value prefixed with @b64@: it will then be possible to mask it and the template will automatically decode it prior to using it.
Don't forget to escape special characters (ex: $ -> $$).

Jobs¶

`docker-hadolint` job¶

This job performs a Lint on your Dockerfile.

It is bound to the build stage, and uses the following variables:

Input / Variable	Description	Default value
`hadolint-disabled` / `DOCKER_HADOLINT_DISABLED`	Set to `true` to disable Hadolint	(none: enabled by default)
`hadolint-image` / `DOCKER_HADOLINT_IMAGE`	The Hadolint image	`registry.hub.docker.com/hadolint/hadolint:latest-alpine`
`hadolint-args` / `DOCKER_HADOLINT_ARGS`	Additional `hadolint` arguments	(none)

In case you have to disable some rules, either add --ignore XXXX to the DOCKER_HADOLINT_ARGS variable or create a Hadolint configuration file named hadolint.yaml at the root of your repository.

You can also use inline ignores in your Dockerfile:

# hadolint ignore=DL3006
FROM ubuntu

# hadolint ignore=DL3003,SC1035
RUN cd /tmp && echo "hello!"

In addition to a textual report in the console, this job produces the following reports, kept for one day:

Report	Format	Usage
`reports/docker-hadolint-*.native.json`	native hadolint test report (json)	DefectDojo integration This report is generated only if DefectDojo template is detected
`reports/docker-hadolint-*.codeclimate.json`	hadolint (GitLab) codeclimate format	GitLab integration

`docker-*-build` jobs¶

This job builds the image and publishes it to the snapshot repository.

It is bound to the package-build stage, and uses the following variables:

Input / Variable	Description	Default value
`build-args` / `DOCKER_BUILD_ARGS`	Additional `docker/kaniko/buildah` `build` arguments	(none)
`registry-mirror` / `DOCKER_REGISTRY_MIRROR`	URL of a Docker registry mirror to use during the image build (instead of default `https://index.docker.io`) Used by the `kaniko` and `dind` options only	(none)
`container-registries-config-file` / `CONTAINER_REGISTRIES_CONFIG_FILE`	The `registries.conf` configuration to be used Used by the `buildah` build only	(none)
`metadata` / `DOCKER_METADATA`	Additional `docker build`/`kaniko` arguments to set label	OCI Image Format Specification
`kaniko-snapshot-image-cache` / `KANIKO_SNAPSHOT_IMAGE_CACHE`	Snapshot image repository that will be used to store cached layers (leave empty to use default: snapshot image repository + `/cache`) Used by the `kaniko` build only	none (default cache path)
`build-cache-disabled` / `DOCKER_BUILD_CACHE_DISABLED`	Set to `true` to disable the build cache. Cache can typically be disabled when there is a network latency between the container registry and the runner.	none (i.e cache enabled)
`push-args` / `DOCKER_PUSH_ARGS`	Additional `push` arguments for docker or buildah (executed right after `build`). Ex: `--compression-format zstd --compression-level 20`	(none)

This job produces output variables that are propagated to downstream jobs (using dotenv artifacts):

Input / Variable	Description	Example
`docker_image`	snapshot image name with tag	`registry.gitlab.com/acme/website/snapshot:main`
`docker_image_digest`	snapshot image name with digest (no tag)	`registry.gitlab.com/acme/website/snapshot@sha256:b7914a91...`
`docker_repository`	snapshot image bare repository (no tag nor digest)	`registry.gitlab.com/acme/website/snapshot`
`docker_tag`	snapshot image tag	`main`
`docker_digest`	snapshot image digest	`sha256:b7914a91...`

They may be freely used in downstream jobs (for instance to deploy the upstream built Docker image, whatever the branch or tag).

If you want to use GitLab CI variables or any other variable in your Dockerfile, you can add them to DOCKER_BUILD_ARGS like so:

DOCKER_BUILD_ARGS: "--build-arg CI_PROJECT_URL --build-arg MY_VAR='MY_VALUE'"

These variables will then be available for use in your Dockerfile:

FROM scratch

ARG CI_PROJECT_URL
ARG MY_VAR
LABEL name="my-project"                   \
      description="My Project: $MY_VAR"   \
      url=$CI_PROJECT_URL                 \
      maintainer="my-project@acme.com"

Default value for DOCKER_METADATA supports a subset of the OCI Image Format Specification for labels and use GitLab CI pre-defined variables to guess the value as follow :

Label	GitLab CI pre-defined variable
`org.opencontainers.image.url`	`$CI_PROJECT_URL`
`org.opencontainers.image.source`	`$CI_PROJECT_URL`
`org.opencontainers.image.title`	`$CI_PROJECT_PATH`
`org.opencontainers.image.ref.name`	`$CI_COMMIT_REF_NAME`
`org.opencontainers.image.revision`	`$CI_COMMIT_SHA`
`org.opencontainers.image.created`	`$CI_JOB_STARTED_AT`

Note that spaces are currently not supported by Kaniko. Therefore, title couldn't be CI_PROJECT_TITLE.

You may disable this feature by setting DOCKER_METADATA to empty or you can override some of the pre-defined label value with the DOCKER_BUILD_ARGS.

DOCKER_BUILD_ARGS: "--label org.opencontainers.image.title=my-project"

If a label contains spaces then quotes need to be correctly escaped:

DOCKER_BUILD_ARGS: '--label "org.opencontainers.image.title=my project"'

or

DOCKER_BUILD_ARGS: |-
  --label "org.opencontainers.image.title=my project"

The DOCKER_METADATA variable can be overwritten in a similar way, but you will need to ensure that all relevant values are added.

If you have defined one of those labels in the Dockerfile, the final value will depend if image is built with Kaniko or Docker in Docker. With Kaniko, the value of the Dockerfile take precedence, while with DinD command-line argument take precedence.

`docker-healthcheck` job¶

this job requires that your runner has required privileges to run Docker-in-Docker. If it is not the case this job will not be run.

This job performs a Health Check on your built image.

It is bound to the package-test stage, and uses the following variables:

Input / Variable	Description	Default value
`healthcheck-disabled` / `DOCKER_HEALTHCHECK_DISABLED`	Set to `true` to disable health check	(none: enabled by default)
`healthcheck-timeout` / `DOCKER_HEALTHCHECK_TIMEOUT`	When testing a Docker Health (test stage), how long (in seconds) wait for the HealthCheck status	`60`
`healthcheck-options` / `DOCKER_HEALTHCHECK_OPTIONS`	Docker options for health check such as port mapping, environment...	(none)
`healthcheck-container-args` / `DOCKER_HEALTHCHECK_CONTAINER_ARGS`	Set arguments sent to the running container for health check	(none)

In case your Docker image is not intended to run as a service and only contains a client tool (like curl, Ansible, ...) you can test it by overriding the Health Check Job. See this example.

Keep in mind that the downloading of the snapshot image by the GitLab runner will be done during the waiting time (max DOCKER_HEALTHCHECK_TIMEOUT). In case your image takes quite some time to be downloaded by the runner, increase the value of DOCKER_HEALTHCHECK_TIMEOUT in your .gitlab-ci.yml file.

`docker-trivy` job¶

This job performs a Vulnerability Static Analysis with Trivy on your built image.

Without any configuration Trivy will run in standalone mode.

If you want to run Trivy in client/server mode, you need to set the DOCKER_TRIVY_ADDR environment variable.

variables:
  DOCKER_TRIVY_ADDR: "https://trivy.acme.host"

It is bound to the package-test stage, and uses the following variables:

Input / Variable	Description	Default value
`trivy-image` / `DOCKER_TRIVY_IMAGE`	The docker image used to scan images with Trivy	`registry.hub.docker.com/aquasec/trivy:latest`
`trivy-addr` / `DOCKER_TRIVY_ADDR`	The Trivy server address (for client/server mode)	(none: standalone mode)
`trivy-security-level-threshold` / `DOCKER_TRIVY_SECURITY_LEVEL_THRESHOLD`	Severities of vulnerabilities to be displayed (comma separated values: `UNKNOWN`, `LOW`, `MEDIUM`, `HIGH`, `CRITICAL`)	`UNKNOWN,LOW,MEDIUM,HIGH,CRITICAL`
`trivy-disabled` / `DOCKER_TRIVY_DISABLED`	Set to `true` to disable Trivy analysis	(none)
`trivy-args` / `DOCKER_TRIVY_ARGS`	Additional `trivy client` arguments	`--ignore-unfixed --vuln-type os --exit-on-eol 1 --detection-priority comprehensive`
`trivy-db-repository` / `DOCKER_TRIVY_DB_REPOSITORY`	OCI repository to retrieve Trivy Database from	none (use Trivy default `ghcr.io/aquasecurity/trivy-db`)
`trivy-java-db-repository` / `DOCKER_TRIVY_JAVA_DB_REPOSITORY`	OCI repository to retrieve Trivy Java Database from	none (use Trivy default `ghcr.io/aquasecurity/trivy-java-db:1`)_

In addition to a textual report in the console, this job produces the following reports, kept for one day:

Report	Format	Usage
`reports/docker-trivy-*.native.json`	native Trivy report format (json)	DefectDojo integration This report is generated only if DefectDojo template is detected
`reports/docker-trivy-*.gitlab.json`	Trivy report format for GitLab format	GitLab integration

`docker-sbom` job¶

This job generates a SBOM file listing installed packages using syft.

It is bound to the package-test stage, and uses the following variables:

Input / Variable	Description	Default value
`sbom-disabled` / `DOCKER_SBOM_DISABLED`	Set to `true` to disable this job	none
`sbom-image` / `DOCKER_SBOM_IMAGE`	The docker image used to emit SBOM	`registry.hub.docker.com/anchore/syft:debug`
`sbom-opts` / `DOCKER_SBOM_OPTS`	Options for syft used for SBOM analysis	`--override-default-catalogers rpm-db-cataloger,alpm-db-cataloger,apk-db-cataloger,dpkg-db-cataloger,portage-cataloger`

`docker-publish` job¶

This job pushes (promotes) the built image as the release image skopeo.

Input / Variable	Description	Default value
`skopeo-image` / `DOCKER_SKOPEO_IMAGE`	The Docker image used to run skopeo	`quay.io/skopeo/stable:latest`
`publish-args` / `DOCKER_PUBLISH_ARGS`	Additional `skopeo copy` arguments	(none)
`prod-publish-strategy` / `DOCKER_PROD_PUBLISH_STRATEGY`	Defines the publish to production strategy. One of `manual` (i.e. one-click), `auto` or `none` (disabled).	`manual`
`release-extra-tags-pattern` / `DOCKER_RELEASE_EXTRA_TAGS_PATTERN`	Defines the image tag pattern that `$DOCKER_RELEASE_IMAGE` should match to push extra tags (supports capturing groups - see below)	`^v?(?P<major>[0-9]+)\\.(?P<minor>[0-9]+)\\.(?P<patch>[0-9]+)(?P<suffix>(?P<prerelease>-[0-9A-Za-z-\\.]+)?(?P<build>\\+[0-9A-Za-z-\\.]+)?)$` (SemVer pattern)
`release-extra-tags` / `DOCKER_RELEASE_EXTRA_TAGS`	Defines extra tags to publish the release image (supports capturing group references from `$DOCKER_RELEASE_EXTRA_TAGS_PATTERN` - see below)	(none)
`semrel-release-disabled` / `DOCKER_SEMREL_RELEASE_DISABLED`	Set to `true` to disable semantic-release integration	none (enabled)

This job produces output variables that are propagated to downstream jobs (using dotenv artifacts):

Input / Variable	Description	Example
`docker_image`	release image name with tag	`registry.gitlab.com/acme/website:main`
`docker_image_digest`	release image name with digest (no tag)	`registry.gitlab.com/acme/website@sha256:b7914a91...`
`docker_repository`	release image bare repository (no tag nor digest)	`registry.gitlab.com/acme/website`
`docker_tag`	release image tag	`main`
`docker_digest`	release image digest	`sha256:b7914a91...`

They may be freely used in downstream jobs (for instance to deploy the upstream built Docker image, whatever the branch or tag).

Using extra tags¶

When publishing the release image, the Docker template might publish it again with additional tags (aliases):

the original published image tag (extracted from $DOCKER_RELEASE_IMAGE) must match $DOCKER_RELEASE_EXTRA_TAGS_PATTERN (semantic versioning pattern by default),
extra tags to publish can be defined in the $DOCKER_RELEASE_EXTRA_TAGS variable, each separated with a whitespace.

the Docker template supports group references substitution to evaluate extra tags:

$DOCKER_RELEASE_EXTRA_TAGS_PATTERN supports capturing groups:
v([0-9]+)\.([0-9]+)\.([0-9]+) has 3 (unnamed) capturing groups, each capturing any number of digits
v(?<major>[0-9]+)\.(?<minor>[0-9]+)\.(?<patch>[0-9]+) has 3 named capturing groups (major, minor and patch), each capturing any number of digits
$DOCKER_RELEASE_EXTRA_TAGS supports capturing group references from $DOCKER_RELEASE_EXTRA_TAGS_PATTERN:
\g1 is a reference to capturing group number 1
\g<major> is a reference to capturing group named major

the default value of $DOCKER_RELEASE_EXTRA_TAGS_PATTERN matches and captures all parts of a standard semantic versioning-compliant tag:

the major group captures the major version
the minor group captures the minor version
the patch group captures the patch version
the prerelease group captures the (optional) pre-release version (including the leading -)
the build group captures the (optional) build version (including the leading +)
the suffix group captures the (optional) entire suffix (including pre-release and/or build)

Example: publish latest, major.minor and major aliases for a SemVer release:

variables:
  # ⚠ don't forget to escape backslash character in yaml
  DOCKER_RELEASE_EXTRA_TAGS: "latest \\g<major>.\\g<minor>\\g<build> \\g<major>\\g<build>"

With this contiguration, the following extra tags would be published:

original tag	extra tags
`main`	none (doesn't match `$DOCKER_RELEASE_EXTRA_TAGS_PATTERN`)
`some-manual-tag`	none (doesn't match `$DOCKER_RELEASE_EXTRA_TAGS_PATTERN`)
`1.2.3`	`latest`, `1.2`, `1`
`1.2.3-alpha.12`	`latest`, `1.2`, `1`
`1.2.3+linux`	`latest`, `1.2+linux`, `1+linux`
`1.2.3-alpha.12+linux`	`latest`, `1.2+linux`, `1+linux`

`semantic-release` integration¶

If you activate the semantic-release-info job from the semantic-release template, the docker-publish job will rely on the generated next version info.

the release will only be performed if a semantic release is present
the tag will be based on SEMREL_INFO_NEXT_VERSION, it will override DOCKER_RELEASE_IMAGE by simply substituting the tag, or adding a tag when there's none.

For instance, in both cases:

DOCKER_RELEASE_IMAGE: "registry.gitlab.com/$CI_PROJECT_NAME"
DOCKER_RELEASE_IMAGE: "registry.gitlab.com/$CI_PROJECT_NAME:$CI_COMMIT_REF_NAME"

The published Docker image will be registry.gitlab.com/$CI_PROJECT_NAME:$SEMREL_INFO_NEXT_VERSION and all subsequent jobs relying on the docker_image variable will be provided with this tag.

When semantic-release detects no release (i.e. either the semantic-release template is misconfigured, or there were simply no feat/fix commits), the docker-publish job will report a warning and no image will be pushed in the release registry. In such a case, the docker_image remains unchanged, and will refer to the snapshot image. Any subsequent job that may deploy to production (Kubernetes or Openshift), should thus be configured not to deploy in this situation. Refer to deployment template for more information.

Finally, the semantic-release integration can be disabled with the DOCKER_SEMREL_RELEASE_DISABLED variable.

Examples¶

Using the GitLab Docker registry¶

This sample is the easiest one as you just have nothing to do.

All template variables are configured by default to build and push your Docker images on the GitLab registry.

Using an external Docker registry¶

With this template, you may perfectly use an external Docker registry (ex: a JFrog Artifactory, a private Kubernetes registry, ...).

Here is a .gitlab-ci.yaml using an external Docker registry:

include:
  - component: $CI_SERVER_FQDN/to-be-continuous/docker/gitlab-ci-docker@5.13.3
    inputs:
      snapshot-image: "registry.acme.host/$CI_PROJECT_NAME/snapshot:$CI_COMMIT_REF_SLUG"
      release-image: "registry.acme.host/$CI_PROJECT_NAME:$CI_COMMIT_REF_NAME"
      # $DOCKER_REGISTRY_USER and $DOCKER_REGISTRY_PASSWORD are defined as secret GitLab variables

Depending on the Docker registry you're using, you may have to use a real password or generate a token as authentication credential.

Building multiple Docker images¶

Here is a .gitlab-ci.yaml that builds 2 Docker images from the same project (uses parallel matrix jobs):

include:
  - component: $CI_SERVER_FQDN/to-be-continuous/docker/gitlab-ci-docker@5.13.3

.docker-base:
  parallel:
    matrix:
      - DOCKER_FILE: "front/Dockerfile"
        DOCKER_SNAPSHOT_IMAGE: "$CI_REGISTRY_IMAGE/front/snapshot:$CI_COMMIT_REF_SLUG"
        DOCKER_RELEASE_IMAGE: "$CI_REGISTRY_IMAGE/front:$CI_COMMIT_REF_NAME"
      - DOCKER_FILE: "back/Dockerfile"
        DOCKER_SNAPSHOT_IMAGE: "$CI_REGISTRY_IMAGE/back/snapshot:$CI_COMMIT_REF_SLUG"
        DOCKER_RELEASE_IMAGE: "$CI_REGISTRY_IMAGE/back:$CI_COMMIT_REF_NAME"

Variants¶

The Docker template can be used in conjunction with template variants to cover specific cases.

Vault variant¶

This variant allows delegating your secrets management to a Vault server.

Configuration¶

In order to be able to communicate with the Vault server, the variant requires the additional configuration parameters:

Input / Variable	Description	Default value
`TBC_VAULT_IMAGE`	The Vault Secrets Provider image to use (can be overridden)	`registry.gitlab.com/to-be-continuous/tools/vault-secrets-provider:latest`
`vault-base-url` / `VAULT_BASE_URL`	The Vault server base API url	none
`vault-oidc-aud` / `VAULT_OIDC_AUD`	The `aud` claim for the JWT	`$CI_SERVER_URL`
`VAULT_ROLE_ID`	The AppRole RoleID	must be defined
`VAULT_SECRET_ID`	The AppRole SecretID	must be defined

Usage¶

Then you may retrieve any of your secret(s) from Vault using the following syntax:

@url@http://vault-secrets-provider/api/secrets/{secret_path}?field={field}

With:

Parameter	Description
`secret_path` (path parameter)	this is your secret location in the Vault server
`field` (query parameter)	parameter to access a single basic field from the secret JSON payload

Example¶

include:
  # main template
  - component: $CI_SERVER_FQDN/to-be-continuous/docker/gitlab-ci-docker@5.13.3
  # Vault variant
  - component: $CI_SERVER_FQDN/to-be-continuous/docker/gitlab-ci-docker-vault@5.7.0
    inputs:
      # audience claim for JWT
      vault-oidc-aud: "https://vault.acme.host"
      vault-base-url: "https://vault.acme.host/v1"
      # $VAULT_ROLE_ID and $VAULT_SECRET_ID defined as a secret CI/CD variable

variables:
  # Secrets managed by Vault
  DOCKER_REGISTRY_SNAPSHOT_USER: "@url@http://vault-secrets-provider/api/secrets/b7ecb6ebabc231/artifactory/snapshot/credentials?field=user"
  DOCKER_REGISTRY_SNAPSHOT_PASSWORD: "@url@http://vault-secrets-provider/api/secrets/b7ecb6ebabc231/artifactory/snapshot/credentials?field=token"
  DOCKER_REGISTRY_RELEASE_USER: "@url@http://vault-secrets-provider/api/secrets/b7ecb6ebabc231/artifactory/release/credentials?field=user"
  DOCKER_REGISTRY_RELEASE_PASSWORD: "@url@http://vault-secrets-provider/api/secrets/b7ecb6ebabc231/artifactory/release/credentials?field=token"

Google Cloud variant¶

This variant allows publishing your container images to Google Cloud's Artifact Registry.

this template doesn't support Google Cloud's Container Registry that is deprecated and whose support will be discontinued in May 2024.

List of requirements before using this variant for publishing your container images:

You must have a Docker repository in Artifact Registry,
You must have a Workload Identity Federation Pool,
You must have a Service Account with enough permissions to push to your Artifact Registry repository.

Configuration¶

Input / Variable	Description	Default value
`TBC_GCP_PROVIDER_IMAGE`	The GCP Auth Provider image to use (can be overridden)	`registry.gitlab.com/to-be-continuous/tools/gcp-auth-provider:latest`
`gcp-oidc-aud` / `GCP_OIDC_AUD`	The `aud` claim for the JWT token	`$CI_SERVER_URL`
`gcp-oidc-provider` / `GCP_OIDC_PROVIDER`	Default Workload Identity Provider associated with GitLab to authenticate with OpenID Connect	none
`gcp-oidc-account` / `GCP_OIDC_ACCOUNT`	Default Service Account to which impersonate with OpenID Connect authentication	none
`gcp-snapshot-oidc-provider` / `GCP_SNAPSHOT_OIDC_PROVIDER`	Workload Identity Provider to push the snapshot image (only define to override default)	none
`gcp-snapshot-oidc-account` / `GCP_SNAPSHOT_OIDC_ACCOUNT`	Service Account to use to push the snapshot image (only define to override default)	none
`gcp-release-oidc-provider` / `GCP_RELEASE_OIDC_PROVIDER`	Workload Identity Provider to push the release image (only define to override default)	none
`gcp-release-oidc-account` / `GCP_RELEASE_OIDC_ACCOUNT`	Service Account to use to push the release image (only define to override default)	none

if using Kaniko, don't forget to either create the cache repository (snapshot image repository + /cache) or override $KANIKO_SNAPSHOT_IMAGE_CACHE to use the snapshot image repository (will host your snapshot image as well as cached layers).

Example¶

include:
  - component: $CI_SERVER_FQDN/to-be-continuous/docker/gitlab-ci-docker@5.13.3
    inputs:
      build-tool: "kaniko" # Only Kaniko has been proved to work for this use case YET
      # untested & unverified container image
      snapshot-image: "{GCP_REGION}-docker.pkg.dev/{GCP_PROJECT_ID}/{YOUR_REPOSITORY}/{YOUR_IMAGE_NAME}/snapshot:$CI_COMMIT_REF_SLUG"
      # ⚠ don't forget to create the '{GCP_REGION}-docker.pkg.dev/{GCP_PROJECT_ID}/{YOUR_REPOSITORY}/{YOUR_IMAGE_NAME}/snapshot/cache' repo for Kaniko
      # validated container image (published)
      release-image: "{GCP_REGION}-docker.pkg.dev/{GCP_PROJECT_ID}/{YOUR_REPOSITORY}/{YOUR_IMAGE_NAME}:$CI_COMMIT_REF_NAME"
  - component: $CI_SERVER_FQDN/to-be-continuous/docker/gitlab-ci-docker-gcp@5.7.0
    inputs:
      # default WIF provider
      gcp-oidc-provider: "projects/{GCP_PROJECT_NUMBER}/locations/global/workloadIdentityPools/{YOUR_WIF_POOL_NAME}/providers/gitlab-diod"
      # default GCP Service Account
      gcp-oidc-account: "{YOUR_REGISTRY_SA}@{GCP_PROJECT_ID}.iam.gserviceaccount.com"
      # WIF provider for snapshot images
      gcp-snapshot-oidc-provider: "projects/{GCP_PROJECT_NUMBER}/locations/global/workloadIdentityPools/{YOUR_WIF_POOL_NAME}/providers/gitlab-diod"
      # GCP Service Account for snapshot images
      gcp-snapshot-oidc-account: "{YOUR_REGISTRY_SA}@{GCP_PROJECT_ID}.iam.gserviceaccount.com"

Amazon Elastic Container Registry¶

This variant allows publishing your container images to Amazon's Elastic Container Registry.

It takes care of retrieving an ECR authorization token that will be used as a temporary credential to login to the ECR registry.

In order to use the AWS APIs, the variant supports two authentication methods:

federated authentication using OpenID Connect (recommended method),
or basic authentication with AWS access key ID & secret access key.

when using this variant, you must have created the ECR repositories to push the snapshot and/or the release images.

Configuration¶

Input / Variable	Description	Default value
`TBC_AWS_PROVIDER_IMAGE`	The AWS Auth Provider image to use (can be overridden)	`registry.gitlab.com/to-be-continuous/tools/aws-auth-provider:latest`
`aws-region` / `AWS_REGION`	Default region (where the ECR registry is located)	none
`aws-snapshot-region` / `AWS_SNAPSHOT_REGION`	Region of the ECR registry for the snapshot image (only define to override default)	none
`aws-release-region` / `AWS_RELEASE_REGION`	Region of the ECR registry for the release image (only define to override default)	none

if using Kaniko, don't forget to either create the cache repository (snapshot image repository + /cache) or override $KANIKO_SNAPSHOT_IMAGE_CACHE to use the snapshot image repository (will host your snapshot image as well as cached layers).

OIDC authentication config¶

This is the recommended authentication method. In order to use it, first carefuly follow GitLab's documentation, then set the required configuration.

Input / Variable	Description	Default value
`aws-oidc-aud` / `AWS_OIDC_AUD`	The `aud` claim for the JWT token	`$CI_SERVER_URL`
`aws-oidc-role-arn` / `AWS_OIDC_ROLE_ARN`	Default IAM Role ARN associated with GitLab	none
`aws-snapshot-oidc-role-arn` / `AWS_SNAPSHOT_OIDC_ROLE_ARN`	IAM Role ARN associated with GitLab for the snapshot image (only define to override default)	none
`aws-release-oidc-role-arn` / `AWS_RELEASE_OIDC_ROLE_ARN`	IAM Role ARN associated with GitLab for the release image (only define to override default)	none

Basic authentication config¶

Variable	Description	Default value
`AWS_ACCESS_KEY_ID`	Default access key ID	none (disabled)
`AWS_SECRET_ACCESS_KEY`	Default secret access key	none (disabled)
`AWS_SNAPSHOT_ACCESS_KEY_ID`	Access key ID for the snapshot image (only define to override default)	none
`AWS_SNAPSHOT_SECRET_ACCESS_KEY`	Secret access key for the snapshot image (only define to override default)	none
`AWS_RELEASE_ACCESS_KEY_ID`	Access key ID for the release image (only define to override default)	none
`AWS_RELEASE_SECRET_ACCESS_KEY`	Secret access key for the release image (only define to override default)	none

Example¶

include:
  - component: $CI_SERVER_FQDN/to-be-continuous/docker/gitlab-ci-docker@5.13.3
    inputs:
      # untested & unverified container image
      snapshot-image: "123456789012.dkr.ecr.us-east-1.amazonaws.com/$CI_PROJECT_PATH_SLUG/snapshot:$CI_COMMIT_REF_SLUG"
      # ⚠ don't forget to create the '123456789012.dkr.ecr.us-east-1.amazonaws.com/$CI_PROJECT_PATH/snapshot/cache' repo for Kaniko
      # validated container image (published)
      release-image: "123456789012.dkr.ecr.us-east-1.amazonaws.com/$CI_PROJECT_PATH_SLUG:$CI_COMMIT_REF_NAME"
  - component: $CI_SERVER_FQDN/to-be-continuous/docker/gitlab-ci-docker-ecr@5.7.0
    inputs:
      # default Role ARN (using OIDC authentication method)
      aws-oidc-role-arn: "arn:aws:iam::123456789012:role/gitlab-ci"
      aws-region: "us-east-1"

GitLab CI template for Docker¶

Usage¶

Use as a CI/CD component¶

Use as a CI/CD template (legacy)¶

Understanding the Docker template¶

Global variables¶

Images¶

Registries and credentials¶

Using the same registry for snapshot and release¶

Using different registries for snapshot and release¶

Setting your own Docker configuration file (advanced)¶

Multi Dockerfile support¶

Secrets management¶

Jobs¶

docker-hadolint job¶

docker-*-build jobs¶

docker-healthcheck job¶

docker-trivy job¶

docker-sbom job¶

docker-publish job¶

Using extra tags¶

semantic-release integration¶

Examples¶

Using the GitLab Docker registry¶

Using an external Docker registry¶

Building multiple Docker images¶

Variants¶

Vault variant¶

Configuration¶

Usage¶

Example¶

Google Cloud variant¶

Configuration¶

Example¶

Amazon Elastic Container Registry¶

Configuration¶

OIDC authentication config¶

Basic authentication config¶

Example¶

`docker-hadolint` job¶

`docker-*-build` jobs¶

`docker-healthcheck` job¶

`docker-trivy` job¶

`docker-sbom` job¶

`docker-publish` job¶

`semantic-release` integration¶