Skip to content

Pipeline execution policies

DETAILS: Tier: Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

FLAG: The availability of this feature is controlled by a feature flag. For more information, see the history.

Use Pipeline execution policies to enforce CI/CD jobs for all applicable projects.

Pipeline execution policies schema

The YAML file with pipeline execution policies consists of an array of objects matching pipeline execution policy schema nested under the pipeline_execution_policy key. You can configure a maximum of five policies under the pipeline_execution_policy key. Any other policies configured after the first five are not applied.

When you save a new policy, GitLab validates its contents against this JSON schema. If you're not familiar with how to read JSON schemas, the following sections and tables provide an alternative.

Field Type Required Description
pipeline_execution_policy array of pipeline execution policy true List of pipeline execution policies (maximum five)

Pipeline execution policy schema

Field Type Required Description
name string true Name of the policy. Maximum of 255 characters.
description (optional) string true Description of the policy.
enabled boolean true Flag to enable (true) or disable (false) the policy.
content object of content true Reference to the CI/CD configuration to inject into project pipelines.
pipeline_config_strategy string false Can either be inject_ci or override_project_ci. Defines the method for merging the policy configuration with the project pipeline. inject_ci preserves the project CI configuration and injects additional jobs from the policy. Having multiple policies enabled injects all jobs additively. override_project_ci replaces the project CI configuration and keeps only the policy jobs in the pipeline.
policy_scope object of policy_scope false Scopes the policy based on compliance framework labels or projects you define.

Note the following:

  • Jobs variables from pipeline execution policies take precedence over the project's CI/CD configuration.
  • Users triggering a pipeline must have at least read access to the pipeline execution file specified in the pipeline execution policy, otherwise the pipelines do not start.
  • If the pipeline execution file gets deleted or renamed, the pipelines in projects with the policy enforced might stop working.
  • Pipeline execution policy jobs can be assigned to one of the two reserved stages:
    • .pipeline-policy-pre at the beginning of the pipeline, before the .pre stage.
    • .pipeline-policy-post at the very end of the pipeline, after the .post stage.
  • Injecting jobs in any of the reserved stages is guaranteed to always work. Execution policy jobs can also be assigned to any standard (build, test, deploy) or user-declared stages. However, in this case, the jobs may be ignored depending on the project pipeline configuration.
  • It is not possible to assign jobs to reserved stages outside of a pipeline execution policy.
  • The override_project_ci strategy will not override other security policy configurations.
  • The override_project_ci strategy takes precedence over other policies using the inject strategy. If any policy with override_project_ci applies, the project CI configuration will be ignored.
  • You should choose unique job names for pipeline execution policies. Some CI/CD configurations are based on job names and it can lead to unwanted results if a job exists multiple times in the same pipeline. The needs keyword, for example makes one job dependent on another. In case of multiple jobs with the same name, it will randomly depend on one of them.
  • Pipeline execution policies remain in effect even if the project lacks a CI/CD configuration file.

Job naming best practice

There is no visible indicator for jobs coming from a security policy. Adding a unique prefix to job names makes it easier to identify them and avoid job name collisions.

Examples:

  • policy1:deployments:sast - good, unique across policies and projects.
  • sast - bad, likely to be used elsewhere.

content type

Field Type Required Description
project string true The full GitLab project path to a project on the same GitLab instance.
file string true A full file path relative to the root directory (/). The YAML files must have the .yml or .yaml extension.
ref string false The ref to retrieve the file from. Defaults to the HEAD of the project when not specified.

policy_scope scope type

Field Type Possible values Description
compliance_frameworks array List of IDs of the compliance frameworks in scope of enforcement, in an array of objects with key id.
projects object including, excluding Use excluding: or including: then list the IDs of the projects you wish to include or exclude, in an array of objects with key id.

Examples

These examples demonstrate what you can achieve with pipeline execution policies.

Pipeline execution policy

You can use the following example in a .gitlab/security-policies/policy.yml file stored in a security policy project:

---
pipeline_execution_policy:
- name: My pipeline execution policy
  description: Enforces CI/CD jobs
  enabled: true
  pipeline_config_strategy: override_project_ci
  content:
    include:
    - project: verify-issue-469027/policy-ci
      file: policy-ci.yml
      ref: main # optional
  policy_scope:
    projects:
      including:
      - id: 361
Customize enforced jobs based on project variables

You can customize enforced jobs, based on the presence of a project variable. In this example, the value of CS_IMAGE is defined in the policy as alpine:latest. However, if the project also defines the value of CS_IMAGE, that value is used instead. The CI/CD variable must be a predefined project variable, not defined in the project's .gitlab-ci.yml file.

variables:
  CS_ANALYZER_IMAGE: "$CI_TEMPLATE_REGISTRY_HOST/security-products/container-scanning:7"
  CS_IMAGE: alpine:latest

policy::container-security:
  stage: .pipeline-policy-pre
  rules:
    - if: $CS_IMAGE
      variables:
        CS_IMAGE: $PROJECT_CS_IMAGE
    - when: always
  script:
    - echo "CS_ANALYZER_IMAGE:$CS_ANALYZER_IMAGE"
    - echo "CS_IMAGE:$CS_IMAGE"