README.md

GitLab CI template for Docker

This project implements a generic GitLab CI template Docker based projects.

Usage

In order to include this template in your project, add the following to your .gitlab-ci.yml :

include:
  - project: 'to-be-continuous/docker'
    ref: '3.5.0'
    file: '/templates/gitlab-ci-docker.yml'

Understanding the Docker template

The template supports two ways of building your Docker images:

1. The former Docker-in-Docker 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),
2. Or using kaniko, an open-source tool from Google for building Docker images, and that solves Docker-in-Docker security issues (and also speeds-up build times).

By default, the template uses the kaniko way, but you may activate the Docker-in-Docker build at your own risks by setting DOCKER_DIND_BUILD to true (see below). ⚠️ In that case, 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.

Name	Description	Default value
DOCKER_DIND_BUILD	Set to enable Docker-in-Docker build (⚠️ unsecured, requires privileged runners).	(none) (kaniko build by default)
DOCKER_KANIKO_IMAGE	The Docker image used to run kaniko - for kaniko build only	gcr.io/kaniko-project/executor:debug (use debug images for GitLab)
DOCKER_IMAGE	The Docker image used to run the docker client (see full list) - for Docker-in-Docker build only	docker:latest
DOCKER_DIND_IMAGE	The Docker image used to run the Docker daemon (see full list) - for Docker-in-Docker build only	docker:dind
DOCKER_FILE	The path to your Dockerfile	./Dockerfile
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:

Name	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:

1. 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.
2. 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: