Building Docker containers with GitLab

This guide demonstrates how to build and push Docker images using Kaniko in a CI environment (e.g., GitLab CI). Kaniko executes Docker builds without needing a Docker daemon.

Setup Requirements

Registry Credentials

Create a Base64-encoded username:password for your container registry. Store this as a protected CI/CD variable (e.g., HARBOR_CRED in GitLab).

Dockerfile

Ensure that a Dockerfile exists in the repository root. Example content:

FROM alpine
CMD ["echo", "Hello World!!"]

Example CI Configuration (gitlab-ci.yml)

stages:
  - docker

docker-job:
  stage: docker
  image:
    name: gcr.io/kaniko-project/executor:debug  # Official Kaniko executor image
    entrypoint: [""]  # Disable default entrypoint
  before_script:
    - echo "{\"auths\":{\"your-registry.io\":{\"auth\":\"${HARBOR_CRED}\"}}}" > /kaniko/.docker/config.json
    - cat /kaniko/.docker/config.json  # Verify config (optional)
  script:
    - export VERSION='0.0.1'  # Set your image version
    # Dynamic tagging logic:
    - |
      if [[ "$CI_COMMIT_BRANCH" == "$CI_DEFAULT_BRANCH" ]]; then
        tag="${VERSION}"
        echo "Default branch '$CI_DEFAULT_BRANCH': tag=$tag"
      else
        tag="${VERSION}-$CI_COMMIT_REF_SLUG"  # Appends branch slug
        echo "Branch '$CI_COMMIT_BRANCH': tag=$tag"
      fi
    # Build and push the image:
    - /kaniko/executor
      --context $CI_PROJECT_DIR
      --dockerfile $CI_PROJECT_DIR/Dockerfile
      --destination "cerit.io/your-project/docker-image:${tag}"
  only:
    - tags  # Trigger on Git tags
    - master  # Or your default branch

Notes

• In before_script, Docker configuration is created using the credential value from your CI variable (here HARBOR_CRED).
• The version value is explicitly set in CI. Consider factoring it out, for example to a version.txt file in the repository, or obtain it from other configuration files in the repository such as setup.py (for Python projects) or package.json (for Node.js projects), etc.
• The tagging logic in the example is tuned for a setup where:
  • The default branch (master) is a protected branch that can only be changed by merge request (i.e., cannot be pushed to directly).
  • Features are developed in a branch.
  • By default, the Docker job is executed only on the master branch (after a merge request).
  • The Docker job can also be executed on demand on a branch commit if that commit is tagged. In that case, the Docker image tag consists of VERSION suffixed by the tag value.
• Check this repository graph and pipeline history.
• See Kaniko documentation for advanced flags (e.g., --cache, --build-arg).
• Keep in mind that Kaniko is probably obsolete.

How to use images from GitLab Registry

If the project’s visibility within GitLab is public and the container registry is not limited to authenticated users, simply use:

docker run [options] registry.example.com/group/project/image [arguments]

If you are using MUNI ICS GitLab, the registry URL is: registry.gitlab.ics.muni.cz

If project visibility or container registry is set to private, authentication to the container registry is needed. You will need to create a deploy token and use it as described in the official documentation.

For more information, please refer to the official documentation.