GitLab CI/CD Configuration using Templates and Extends

GitLab CI/CD allows you to streamline your continuous integration and continuous deployment processes using a configuration file, typically named .gitlab-ci.yaml. In this blog post, we’ll explore how to organize your GitLab CI/CD configuration by utilizing templates and extends for better maintainability and readability.

Introduction

GitLab CI/CD is a powerful tool for automating the building, testing, and deployment of your software projects. In this guide, we’ll focus on creating a structured .gitlab-ci.yaml file using templates and extends to simplify and organize our CI/CD pipeline configuration.

Basic Configuration

# Define the stages for the pipeline
stages:
  - build
  - test
  - deploy

# Define project-wide variables
variables:
  ARTIFACTS_DIR: "artifacts"

# Define a pipeline-wide before_script
before_script:
  - echo "Setting up the environment..."

In this basic configuration, we’ve defined three stages (build, test, and deploy), project-wide variables, and a pipeline-wide before_script that runs before each job.

Templates for Build

# Define a job template for the 'build' stage
.build_template:
  script:
    - echo "Building the project..."
    - mkdir -p $ARTIFACTS_DIR
    - touch $ARTIFACTS_DIR/build_artifact.txt
  artifacts:
    paths:
      - $ARTIFACTS_DIR/*

Here, we’ve created a template named .build_template for the ‘build’ stage. It includes common build steps such as creating directories and generating artifacts.

Extending Templates

# Define jobs that extend the 'build' template
job1:
  stage: build
  extends: .build_template
  script:
    - echo "Additional steps for job1..."

job2:
  stage: build
  extends: .build_template
  script:
    - echo "Additional steps for job2..."

# Define a job that extends the 'build' template but with additional steps
custom_job:
  stage: build
  extends: .build_template
  script:
    - echo "Custom steps for this job..."
    - echo "More custom steps..."

In this section, we’ve created jobs (job1, job2, and custom_job) that extend the .build_template. These jobs inherit the common build steps and can include their own specific steps.

Testing Stage

# Define another template for the 'test' stage
.test_template:
  script:
    - echo "Running tests..."
  dependencies:
    - job1
    - job2

# Define a job that extends both 'build' and 'test' templates
test_job:
  stage: test
  extends:
    - .build_template
    - .test_template
  script:
    - echo "Additional test steps..."

Here, we’ve introduced a .test_template for the ‘test’ stage, including common test steps and specifying dependencies on previous ‘build’ stage jobs. The test_job then extends both .build_template and .test_template.

Deployment Stage

# Define a final job for deployment
deploy:
  stage: deploy
  script:
    - echo "Deploying the application..."

Finally, we have a simple deployment job named deploy in the ‘deploy’ stage. This job is independent of the previous stages but can be extended or customized as needed.

Using YAML anchors

# Define a job template for the 'build' stage
.build_template: &build_test-template
  script:
    - echo "Building the project..."
    - mkdir -p $ARTIFACTS_DIR
    - touch $ARTIFACTS_DIR/build_artifact.txt
  artifacts:
    paths:
      - $ARTIFACTS_DIR/*

build:
  stage: build
  <<: *build_test-template
  script:
  - echo "Additional steps for job1..."

GitLab CI/CD templates and extends allow you to reuse common CI/CD configuration across multiple projects

GitLab CI/CD templates and extends allow you to reuse common CI/CD configuration across multiple projects. This can save you time and effort, and it can also help to ensure that your CI/CD pipelines are consistent.

Templates

Templates are reusable YAML files that define a set of CI/CD jobs. You can use templates to create pipelines for new projects, or you can add them to existing pipelines to add new functionality.

To create a template, you can use the gitlab-ci.yml file in the root of your GitLab project. Alternatively, you can create a new file in the .gitlab/templates/ directory.

The following is an example of a simple template that defines a job to build and test a Node.js application:

stages:
  - build
  - test

build:
  stage: build
  script:
    - npm install
    - npm run build

test:
  stage: test
  script:
    - npm run test

Extends

The extends keyword allows you to reuse the configuration from a template in another CI/CD pipeline. To use the extends keyword, you simply add it to the top of your .gitlab-ci.yml file, followed by the path to the template file.

For example, the following .gitlab-ci.yml file extends the template defined in the build-test.yml file:

extends: .gitlab/templates/build-test.yml

Using Templates and Extends Together

You can use templates and extends together to create complex CI/CD pipelines. For example, you could create a template that defines a set of common jobs, and then extend that template in multiple pipelines to add project-specific jobs.

The following is an example of a CI/CD pipeline that uses templates and extends to create a pipeline for a Node.js application:

# .gitlab-ci.yml

extends: .gitlab/templates/build-test.yml

stages:
  - deploy

deploy:
  stage: deploy
  script:
    - npm run deploy

This pipeline extends the build-test.yml template, which defines the build and test jobs. The pipeline also defines a deploy job, which is specific to this project.

Conclusion

Organizing your GitLab CI/CD configuration using templates and extends can greatly enhance the maintainability and readability of your pipeline. This modular approach allows you to reuse common configurations, making it easier to manage and scale your CI/CD setup as your project grows.

Feel free to adapt and expand upon this example to suit the specific needs of your project. Happy coding!

DevToolHub