README.md

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: gitlab.com/to-be-continuous/docker/gitlab-ci-docker@5.10.2
    # 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.10.2'
    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:

1. 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),
2. 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).
3. 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