How to Create and Use Reusable Docker Build Templates in GitLab CI/CD

Creating a Reusable Docker Build Template in GitLab CI/CD

In a modern CI/CD pipeline, building and pushing Docker images is a common requirement. However, many projects use the same steps for Docker image builds, so it makes sense to abstract these steps into reusable templates. This article will walk you through how to create and use a reusable Docker build template in GitLab CI/CD, so you can reuse the same configurations across multiple projects.

Why Use Reusable Docker Build Templates?

When you define the Docker build process in every project separately, you might find yourself repeating the same configurations over and over. Not only does this increase the chance of mistakes, but it also makes your CI/CD pipeline harder to maintain. By using reusable templates, you can:

• Centralize common configurations: Have all your Docker build steps defined in one place.
• Reduce duplication: Reuse the same configurations across multiple projects.
• Improve maintainability: When changes are needed, they can be made in one place, automatically applying to all projects using the template.
• Enhance consistency: Every project will follow the same Docker build process, ensuring uniformity across environments.

---

How to Create a Reusable Docker Build Template

The basic idea of a reusable template is to define a set of steps (like building and pushing Docker images) in a template file, which can then be used in multiple projects. Here’s how you can do this.

1. Create the Reusable Docker Build Template

The first step is to create the reusable Docker build template itself. This template will contain the common build logic, including Docker login, building the image, and pushing it to a container registry.

You should define this in a .yml file, which will be referenced later by the projects that need it.

Example Reusable Docker Build Template (reusable-docker-build.yml):

# Reusable Docker Build Template

stages:

  - build

 

.docker-build-template:

  stage: build

  image: docker:latest  # Using the official Docker image for building

  services:

    - docker:dind  # Docker-in-Docker service for building images

  variables:

    DOCKER_HOST: tcp://docker:2375  # Enabling Docker access via TCP

    DOCKER_DRIVER: overlay2  # The Docker storage driver to use

  script:

    # Step 1: Docker login to GitLab Container Registry

    - echo "Logging in to GitLab Container Registry"

    - echo $CI_REGISTRY_PASSWORD | docker login -u $CI_REGISTRY_USER $CI_REGISTRY --password-stdin

 

    # Step 2: Build the Docker image

    - echo "Building the Docker image"

    - docker build -t $IMAGE_NAME:$TAG .

 

    # Step 3: Push the Docker image to the registry

    - echo "Pushing the Docker image"

    - docker push $IMAGE_NAME:$TAG

 

  rules:

    # Trigger this job for specific branches or tags

    - if: $CI_COMMIT_BRANCH == "main"

    - if: $CI_COMMIT_TAG

This template defines:

• Stages: The pipeline’s stages, with build as the only stage here.
• Image: Specifies the Docker image used for the job.
• Services: Enables Docker-in-Docker (docker:dind), allowing Docker commands to run inside the CI/CD job.
• Variables: Configures environment variables like DOCKER_HOST for Docker’s communication channel.
• Script: The sequence of commands to build and push the Docker image.
• Rules: Defines when this template should run (e.g., on the main branch or tags).

---

2. Include the Reusable Template in Your GitLab Project

Now that we have the template file (reusable-docker-build.yml), we can include it in other GitLab projects where you want to use the same Docker build logic.

Example Project .gitlab-ci.yml:

# Include the reusable CI/CD component for Docker build

include:

  - project: 'tcs_cmi/marim/docker-components'  # The shared repository with the reusable template

    file: '/template/reusable-docker-build.yml'  # Path to the reusable Docker build template

 

# Define a visible job to build and push the Docker image

build_image:

  extends: .docker-build-template  # This job will inherit configurations from the template

  variables:

    IMAGE_NAME: $CI_REGISTRY_IMAGE  # Unique image name based on project repository

    TAG: $CI_COMMIT_REF_NAME  # Use the current Git reference (branch or tag) as the image tag

In the above .gitlab-ci.yml file:

• include: Specifies the path to the reusable template. This file is fetched from another repository (tcs_cmi/marim/docker-components) that holds the reusable-docker-build.yml template.
• extends: Inherits all configurations from the template (.docker-build-template), so the job will automatically use the same steps defined in the reusable template.
• Variables: You can customize the job’s variables (e.g., IMAGE_NAME and TAG) specific to your project, overriding default values in the template.

---

3. Customizing the Docker Build Job

The great thing about using a reusable Docker build template is that you can customize specific aspects of the build process without having to change the template itself. The key customizations can be done in the variables section of the project’s .gitlab-ci.yml file.

Here are a few things you might want to customize for your project:

• IMAGE_NAME: You can use $CI_REGISTRY_IMAGE to automatically generate the image name from the GitLab registry or set it manually.
• TAG: Use $CI_COMMIT_REF_NAME to automatically set the tag based on the branch or tag being pushed.
• Other Variables: You can add custom environment variables to control the build process.

---

Benefits of Using Reusable Docker Build Templates

1. Efficiency: Reusable templates reduce the need to define the same Docker build steps across multiple projects, saving you time and effort.
2. Consistency: Ensures that all projects follow the same process for building and pushing Docker images.
3. Maintainability: When you need to change the Docker build process (e.g., update the base image), you can do it in the template, and all projects using it will automatically be updated.
4. Scalability: As your organization grows and you manage more Docker images and CI/CD pipelines, templates allow you to scale easily.

---

Conclusion

By creating and using a reusable Docker build template in GitLab CI/CD, you can streamline your pipeline configurations, ensure consistency across projects, and simplify maintenance. Instead of duplicating the same Docker build steps across multiple .gitlab-ci.yml files, you can define a single template and reuse it as needed. This approach will save you time, reduce errors, and make your CI/CD pipelines easier to manage.