Validate CI/CD Templates at system-level for aligning the behaviors
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,
- Each template doesn't declare whether it's pipeline or job type.
- We have no idea which GitLab group is responsible to maintain the template.
- We have no idea what arguments the template can accept and whether it's required or optional.
- Some job templates are including global keywords, which is problematic when multiple templates are included, because they are overriding each other.
- Inconsistent
stages
keyword usage in Security templates https://www.youtube.com/watch?v=59r7F7dIbUU&ab_channel=GitLabUnfiltered !56843 (comment 538332191)
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
- It must not include global keywords except
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