Skip to content

Validate CI/CD Templates at system-level for aligning the behaviors

Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.

Problem

CI/CD template is the feature to let users to easily setup automated tasks in their CI/CD workflow. Users can include the provided template with include keyword in their .gitlab-ci.yml or they can copy-paste the whole content of the template to overwrite their .gitlab-ci.yml.

However, the provided CI/CD templates are pretty much inconsistent/out-of-control, for example,

We have a development guideline for the CI/CD template development and dedicated citemplates maintainer/reviewers group, however, since it's manual reviewing process, we could easily miss the "gatchas". We're lacking tests in our daily pipeline to systematically check that each template change doesn't violate the guideline.

We also have a plan to let any users host their CI/CD template registry (e.g. Marketplace). In such case, our guideline won't be effective in their registry, so that there is a risk that our templates and their templates won't be integrated well.

Overall, we're lacking system-level validation/consistency check.

Proposal

To explicitly define the spec of a template, we allow users to attach metadata into a template file. More specifically, we introduce template keyword in .gitlab-ci.yml and users must define the metadata properly, otherwise the template will be rejected by the system.

The template keyword accepts the following attributes:

Attribute Required Description
category Yes The category of the template
name Yes The name of the template.
description Yes The description that end-users can understand the purpose and usage of this template.
type Yes The type of the template. This triggers additional validation.
maintainer Yes The maintainer who is responsible to maintain the template (e.g. GitLab group name)

Here is an example:

template:
  category: General
  name: Auto-DevOps
  description: |
    This template is used for bootstrapping Auto DevOps workflow.
    For the basic usage of Auto DevOps, please see https://docs.gitlab.com/ee/topics/autodevops/.
    For customizing the workflow, please see https://docs.gitlab.com/ee/topics/autodevops/customize.html.
  type: pipeline
  maintainer: group::configure

# And the main content starts from here...
job:
  script: ...

At first, we use this metadata validation in our CI/CD templates i.e. lib/gitlab/ci/templates/*.

Per-type template validation

Following the guideline, the additional validation happens on each template type. If the validation fails, it results in YAML error at pipeline creation.

Validation for Pipeline type template

  • If the template has include keyword, it must include job-type templates only.

Validation for Job type template

Notes

  • Some templates have outstanding guideline violations that can't be fixed easily. We'll introduce a feature flag or something to skip the validation for particular templates for now. We can follow-up separately.

Further details

  • We'll support CI/CD templates registry.
  • Users can create a project and submit the templates as packages/libraries.
  • Template sometimes require a custom docker image, the image should be produced in the same library project. e.g. https://gitlab.com/gitlab-org/cluster-integration/auto-deploy-image. This resolves the maintenance headache of updating docker image => gitlab-org/gitlab repo.

Related

  • #323727 (closed)
  • Please see the PoC in !57785 (closed).
  • In the future, we support template:arguments keyword to define the the required/optional environment variables to control the template behavior. e.g.
template:
  ...
  arguments:
    - name: CI_COMMIT_REF_NAME
      type: String
      purpose: To compose the Kubernetes namespace.
    - name: DISABLE_TEST_STAGE
      type: Boolean
      purpose: To disable unwanted test stage in Auto DevOps.
      optional: true
Edited by 🤖 GitLab Bot 🤖