Container Build

The container-build job is used to build Docker container images using Kaniko. Kaniko is a tool to build container images from a Dockerfile inside a container or Kubernetes cluster without requiring a Docker daemon.

Overview

This job:

• Builds Docker container images using Kaniko executor
• Tags images with branch name and commit SHA
• Pushes images to the GitLab Container Registry
• Creates a pipeline.env file with the image tag for use in subsequent jobs

Variables

The following variables can be configured:

Variable	Description	Default	Required
DOCKER_BUILD_IMAGE	Kaniko executor Docker image	'gcr.io/kaniko-project/executor:v1.14.0-debug'	No
ENTRYPOINT	Entrypoint override for the Kaniko image	[""]	No

Variable Details

• DOCKER_BUILD_IMAGE: The Kaniko executor image used to build containers. Defaults to gcr.io/kaniko-project/executor:v1.14.0-debug. The -debug variant includes additional debugging tools.
• ENTRYPOINT: Allows overriding the default entrypoint of the Kaniko image. Defaults to an empty array [""] to use Kaniko's default entrypoint.

GitLab CI/CD Variables

The job also uses the following built-in GitLab CI/CD variables:

• CI_PROJECT_DIR: The full path where the repository is cloned
• CI_REGISTRY_IMAGE: The address of the container registry tied to the project
• CI_COMMIT_REF_NAME: The branch or tag name for which the project is built
• CI_COMMIT_SHORT_SHA: The first 8 characters of the commit revision

Usage

Basic Usage

To use the container-build job in your pipeline, include it in your .gitlab-ci.yml:

variables:
  DOCKER_BUILD_IMAGE: 'gcr.io/kaniko-project/executor:v1.14.0-debug'
  ENTRYPOINT: [""]

.container-build:
  image: $DOCKER_BUILD_IMAGE
  entrypoint: $ENTRYPOINT
  script:
    - CI_COMMIT_REF_NAME=${CI_COMMIT_REF_NAME/\//_}    
    - /kaniko/executor
      --context "${CI_PROJECT_DIR}"
      --dockerfile "${CI_PROJECT_DIR}/Dockerfile"
      --destination "${CI_REGISTRY_IMAGE}:${CI_COMMIT_REF_NAME}_${CI_COMMIT_SHORT_SHA}"
    - echo ${CI_COMMIT_REF_NAME}_${CI_COMMIT_SHORT_SHA} > pipeline.env

Customizing Variables

You can override the default variables to customize the build:

variables:
  DOCKER_BUILD_IMAGE: 'gcr.io/kaniko-project/executor:v1.19.0-debug'
  ENTRYPOINT: [""]

.container-build:
  image: $DOCKER_BUILD_IMAGE
  entrypoint: $ENTRYPOINT
  script:
    - CI_COMMIT_REF_NAME=${CI_COMMIT_REF_NAME/\//_}    
    - /kaniko/executor
      --context "${CI_PROJECT_DIR}"
      --dockerfile "${CI_PROJECT_DIR}/Dockerfile"
      --destination "${CI_REGISTRY_IMAGE}:${CI_COMMIT_REF_NAME}_${CI_COMMIT_SHORT_SHA}"
    - echo ${CI_COMMIT_REF_NAME}_${CI_COMMIT_SHORT_SHA} > pipeline.env

Job Details

Script Steps

The job executes the following steps:

1. Normalize branch name:

   CI_COMMIT_REF_NAME=${CI_COMMIT_REF_NAME/\//_}

   Replaces forward slashes (/) with underscores (_) in the branch name. This is necessary because Docker image tags cannot contain forward slashes.

2. Build and push image:

   /kaniko/executor
     --context "${CI_PROJECT_DIR}"
     --dockerfile "${CI_PROJECT_DIR}/Dockerfile"
     --destination "${CI_REGISTRY_IMAGE}:${CI_COMMIT_REF_NAME}_${CI_COMMIT_SHORT_SHA}"
   • --context: Sets the build context to the project directory
   • --dockerfile: Specifies the path to the Dockerfile (defaults to Dockerfile in the project root)
   • --destination: Sets the image tag and registry destination. The tag format is: {branch_name}_{commit_sha}

3. Create pipeline.env file:

   echo ${CI_COMMIT_REF_NAME}_${CI_COMMIT_SHORT_SHA} > pipeline.env

   Creates a file containing the image tag that can be used by subsequent jobs in the pipeline.

Image Tagging

The built image is tagged using the format:

{CI_REGISTRY_IMAGE}:{CI_COMMIT_REF_NAME}_{CI_COMMIT_SHORT_SHA}

For example:

• Branch: feature/new-feature
• Commit SHA: abc12345
• Image tag: registry.gitlab.com/group/project:feature_new-feature_abc12345

Note: Forward slashes in branch names are replaced with underscores in the tag.

Example Pipeline

Here's an example of how to use container-build in a complete pipeline:

variables:
  DOCKER_BUILD_IMAGE: 'gcr.io/kaniko-project/executor:v1.14.0-debug'
  ENTRYPOINT: [""]

stages:
  - build
  - deploy

.container-build:
  image: $DOCKER_BUILD_IMAGE
  entrypoint: $ENTRYPOINT
  script:
    - CI_COMMIT_REF_NAME=${CI_COMMIT_REF_NAME/\//_}    
    - /kaniko/executor
      --context "${CI_PROJECT_DIR}"
      --dockerfile "${CI_PROJECT_DIR}/Dockerfile"
      --destination "${CI_REGISTRY_IMAGE}:${CI_COMMIT_REF_NAME}_${CI_COMMIT_SHORT_SHA}"
    - echo ${CI_COMMIT_REF_NAME}_${CI_COMMIT_SHORT_SHA} > pipeline.env
  artifacts:
    reports:
      dotenv: pipeline.env
  only:
    - branches
    - tags

build:
  extends: .container-build
  stage: build

Using the Image Tag in Subsequent Jobs

The pipeline.env file created by this job can be used in subsequent jobs:

deploy:
  stage: deploy
  script:
    - echo "Deploying image: ${CI_REGISTRY_IMAGE}:${CI_COMMIT_REF_NAME}_${CI_COMMIT_SHORT_SHA}"
    - kubectl set image deployment/myapp app=${CI_REGISTRY_IMAGE}:${CI_COMMIT_REF_NAME}_${CI_COMMIT_SHORT_SHA}
  dependencies:
    - build

Or by using GitLab's dotenv artifacts:

.container-build:
  # ... other configuration ...
  artifacts:
    reports:
      dotenv: pipeline.env

deploy:
  stage: deploy
  script:
    - echo "Image tag from pipeline.env is available as CI variable"

Prerequisites

• A Dockerfile must exist in the project root (or specify a custom path)
• The GitLab Container Registry must be enabled for the project
• The runner must have permissions to push to the container registry

Notes

• Kaniko builds images without requiring a Docker daemon, making it suitable for containerized CI/CD environments
• The -debug variant of the Kaniko image includes additional tools for troubleshooting
• Branch names with forward slashes are automatically converted to underscores in image tags
• The pipeline.env file can be used as a dotenv artifact to make the image tag available to other jobs
• Images are automatically pushed to the GitLab Container Registry during the build process