Utilities for building docker images using GitLab CI.
docker-template.yml contains two pipeline configurations:
- Build builds a Docker image in GitLab CI (default).
- Update-Check performs an update check and triggers Build accordingly.
When the following configuration is saved as .gitlab-ci.yml in the same directory as a Dockerfile, GitLab CI will build an image for the platforms AMD64
and ARMv7 and publish them to the Docker registry:
include:
remote: "https://github.com/git-developer/docker-support/raw/v3.3.1/gitlab-ci/docker-template.yml"This pipeline is enabled by default or when the variable PIPELINE_MODE is set to build.
| Step | Stage | Job | Description | Default |
|---|---|---|---|---|
| 1a | post_checkout | prepare_tags | Read tags | latest |
| 1b | post_checkout | prepare_labels | Read labels. | All annotations defined by the Open Container Initiative. The values are determined automatically from git repository metadata. |
| 2 | pre_build | prepare_build_arguments | Read build arguments | none |
| 3 | build | build_image | Build the image for all target platforms. | linux/amd64,linux/arm/v7 |
| 4 | push | publish_image | Add all tags and labels to the image and publish it to a Docker registry. |
This pipeline is enabled when the variable PIPELINE_MODE is set to update-check.
| Step | Stage | Job | Description |
|---|---|---|---|
| 1 | post_checkout | trigger_on_update | Check if one of the UPDATE_CHECK_URLS is newer than the Docker image. If so, trigger the pipeline Build. |
To specify the target platforms, set the variable IMAGE_PLATFORMS. Example:
variables:
IMAGE_PLATFORMS: 'linux/i386,linux/arm/v6'To publish to Docker hub, set the following variables within the CI/CD settings in GitLab:
| Key | Value |
|---|---|
CI_REGISTRY |
docker.io |
CI_REGISTRY_USER |
Username for Docker Hub |
CI_REGISTRY_PASSWORD |
Access Token for Docker Hub |
It is highly recommended to generate an Access Token on Docker Hub and use it in place of the password.
- To replace the default tag
latest, set the variableIMAGE_VERSION. Example:variables: IMAGE_VERSION: "newest"
- Add tags:
- Create the directory
tags - For each tag, create a file within this directory and write the tag to it. Example:
Add Some Tag: stage: prepare script: - mkdir -p tags - echo "${IMAGE_NAME}:fancy-tag" >"tags/fancy-tag" artifacts: paths: - tags
- Create the directory
- Add labels:
- Create the directory
labels - For each label, create a file within this directory and write the label 8336 to it. Example:
Add Some Label: stage: prepare script: - mkdir -p labels - echo "com.example.some-label=some-value" >"labels/some-label" artifacts: paths: - labels
- Create the directory
-
When the build arguments do not contain spaces or special characters, simply put them into the variable
BUILD_ARGS. Example:variables: BUILD_ARGS: 'APP_NAME=foo-app APP_URL=http://example.org/foo'
-
When the build arguments contain special characters:
- Create the directory
build-args - For each build argument, create a file within this directory and write the build argument to it. Example:
Add Some Build Arguments: stage: setup script: - mkdir -p build-args - printf "foo bar\nbaz" >build-args/some-build-arg artifacts: paths: - build-args
- Create the directory
The job .docker_support:.with_bare_image may be used to analyze the built
image, or even start a container from it, before publishing to the registry.
The following example uses the busybox version as image tag:
include:
remote: "https://github.com/git-developer/docker-support/raw/v3.3.1/gitlab-ci/docker-template.yml"
stages:
- setup
- prepare
- analyze
- publish
Collect Additional Tags:
extends: .docker_support:.with_bare_image
stage: analyze
artifacts:
paths:
- tags
script:
- echo >tags/version "${IMAGE_NAME}:busybox-$(docker run --rm "${IMAGE_NAME}:${BUILD_CACHE}" sh -c 'busybox | head -1 | cut -d " " -f 2')"The Pipeline Update-Check is designed for projects that download and build an application hosted externally.
To automatically build a project whenever an
external resource is updated, create a
pipeline schedule
in GitLab with an interval of your choice (e.g. Every day) and set the variable
PIPELINE_MODE to update-check.
The variable UPDATE_CHECK_URLS is used to check the date of one or more
external resources. It may contain a space-separated list of URLs pointing to a
HTTP resource or a git repository. If the latest Docker image (multi-platform)
tagged with the value of variable IMAGE_VERSION is outdated,
a pipeline for project DOWNSTREAM_PROJECT on branch DOWNSTREAM_REF is
triggered. The variables for project and ref default to the current
environment, so that by default the current project is build.
The variable UPDATE_CHECK_URLS may be defined where it is most appropriate,
e.g. in the pipeline schedule or in the project's .gitlab-ci-yml, e.g.
variables:
UPDATE_CHECK_URLS: 'https://www.example.org/ https://github.com/demo-group/demo-repo.git'The date of the Docker images is read from a Docker registry,
defaulting to Docker Hub.
The following variables may be used to configure a custom registry
(see docker-support.yml for default values):
REGISTRY_BASE_URLREGISTRY_AUTH_BASE_URLREGISTRY_AUTH_SERVICE
This job supports registry authentication. If the registry requires credentials, the pre-defined variables are used (usually defined as GitLab project or group variable):
CI_REGISTRY_USERCI_REGISTRY_PASSWORD
docker-support.yml contains the building
blocks for docker-template.yml. It may be used to create custom build
configurations if docker-template.yml is not sufficient.