Skip to content

Conditional includes in .gitlab-ci.yml file

Release notes

Include is one of the most popular keywords to use when writing a full CI/CD pipeline, if you are are building GitLab pipelines, you are probably using the include keyword in your pipeline configuration, as it allows you to bring external YAML configuration into your CI/CD pipeline, include is also using in Parent child and multi project pipeline, in this release we are allowing you to conditional your includes, so in a single pipeline you can decide when should or shouldn't include external CI/CD configuration, this will make your pipeline more dynamic

Problem to solve

As an engineer who builds CI/CD pipelines, I want to conditionally include job definitions so that I can build a more consistent and extendable library of CI jobs that can be shared across projects.

Currently, it's not possible to conditionally include jobs in CI/CD pipelines, which users may want to do in the event they have a library of shared job definitions. One of the biggest hurdles to this is YAML namespace collisions, which we currently address via parent/child pipelines. While this solution, particularly dynamic child pipelines, does work, it's still difficult to implement a number of shared job definitions from a single source (i.e. one project that's used as a CI "library") across multiple projects.

I'm creating this on behalf of a customer, who I think raised some really good points in their ticket: https://gitlab.zendesk.com/agent/tickets/177222 (ZD internal only)

Intended users

Personas are described at https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/

User experience goal

The workflow to address is reusing jobs across multiple pipelines. The goal is to prevent namespace collisions by including those jobs only under certain circumstances rather than generating the job conditionally. It's a quality of life improvement - the current method isn't necessarily broken, but it introduces a lot of extra moving parts.

Proposal

The proposed syntax would look like this:

# file: /templates/common.gitlab-ci.yml
variables:
  __TEMPLATES_COMMON_YML__: true


# file: /templates/docker/build.gitlab-ci.yml"
include:
  - local: "/templates/common.gitlab-ci.yml"
    rules:
      - if: $__TEMPLATES_COMMON_YML__
        when: never

This uses the familiar rules syntax along with include, which is readable and concise. As far as implementation, we already do something similar with workflow. The conditions here would be evaluated as part of the merging of the YAML, and the defined template would only be merged into the pipeline for processing if the rules evaluate to true.

Further details

Permissions and Security

This would not impact permissions or security as far as I can tell. It's a feature enhancement that already has a set of well-defined permissions that wouldn't need to change.

Documentation

Availability & Testing

Requires unit tests for the changes we're introducing/updating here. Integration and E2E tests not required.

What does success look like, and how can we measure that?

What is the type of buyer?

Is this a cross-stage feature?

No, this is a highly specific feature enhancement to CI/CD and the verify stage.

Links / references

This page may contain information related to upcoming products, features and functionality. It is important to note that the information presented is for informational purposes only, so please do not rely on the information for purchasing or planning purposes. Just like with all projects, the items mentioned on the page are subject to change or delay, and the development, release, and timing of any products, features, or functionality remain at the sole discretion of GitLab Inc.

Edited by 🤖 GitLab Bot 🤖