• Pipeline execution policies schema
• Pipeline execution policy schema
  • Job naming best practice
  • content type
  • policy_scope scope type
  • Examples
    • Pipeline execution policy
      • Customize enforced jobs based on project variables

Pipeline execution policies

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

• For a video walkthrough, see Security Policies: Pipeline Execution Policy Type.

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.

Pipeline execution policy schema

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

policy_scope scope type

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"