• Pipeline execution policies schema
• Pipeline execution policy schema
  • Job naming best practice
  • Job stage best practice
  • content type
  • skip_ci type
  • Policy scope schema
• Pipeline strategies
  • inject_ci
  • override_project_ci
  • Include a project’s CI/CD configuration in the pipeline execution policy configuration
• CI/CD variables
• Behavior with [skip ci]
• Interaction with scan execution policies
• Examples
  • Pipeline execution policy
  • Customize enforced jobs based on project variables
  • Customize security scanner’s behavior with before_script in project configurations
  • Use group or project variables in a pipeline execution policy
  • Enforce a variable’s value by using a pipeline execution policy
  • Example policy.yml with security policy scopes

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 per security policy project. 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:

• 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.
• Regardless of the needs keyword, all jobs in a pipeline must wait until the .pipeline-policy-pre stage is complete before they start processing.
• Choose unique job names for pipeline execution policies. Some CI/CD configurations are based on job names, which can lead to unwanted results if a job name exists multiple times in the same pipeline. For example, the needs keyword makes one job dependent on another. If the are multiple jobs with the name example, a job that needs the example job name depend on only one of the example job instance at random.
• Pipeline execution policies remain in effect even if the project lacks a CI/CD configuration file.
• The order of the policies matters for the applied suffix.
• If any policy applied to a given project has suffix: never, the pipeline fails if another job with the same name is already present in the pipeline.
• Pipeline execution policies are enforced on all branches and pipeline sources. You can use workflow rules to control when pipeline execution policies are enforced.

Job naming best practice

There is no visible indicator for jobs coming from a security policy. Adding a unique prefix or suffix 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.

Pipeline execution policies handles naming conflicts depending on the suffix attribute. If there are multiple name with the same job:

• Using on_conflict (default), a suffix is added to a job if its name conflicts with another job in the pipeline.
• Using never, no suffix is added in case of conflicts and the pipeline fails.

The suffix is added based on the order in which the jobs are merged onto the main pipeline.

The order is as follows:

1. Project pipeline jobs
2. Project policy jobs (if applicable)
3. Group policy jobs (if applicable, ordered by hierarchy, the most top-level group is applied as last)

The applied suffix has the following format:

:policy-<security-policy-project-id>-<policy-index>.

Example of the resulting job: sast:policy-123456-0.

If multiple policies in on security policy project define the same job name, the numerical suffix corresponds to the index of the conflicting policy.

Example of the resulting jobs:

• sast:policy-123456-0
• sast:policy-123456-1

Job stage best practice

Jobs defined in a pipeline execution policy can use any stage defined in the project’s CI/CD configuration, also the reserved stages .pipeline-policy-pre and .pipeline-policy-post.

When using the inject_ci pipeline strategy, if a target project does not contain its own .gitlab-ci.yml file, then the only stages available are the default pipeline stages and the reserved stages.

When enforcing pipeline execution policies over projects whose CI/CD configuration you do not control, you should define jobs in the .pipeline-policy-pre and .pipeline-policy-post stages. These stages are always available, regardless of any project’s CI/CD configuration.

When you use the override_project_ci pipeline strategy with multiple pipeline execution policies and with custom stages, the stages must be defined in the same relative order to be compatible with each other:

Valid configuration example:

  - `override-policy-1` stages: `[build, test, policy-test, deploy]`
  - `override-policy-2` stages: `[test, deploy]`

Invalid configuration example:

  - `override-policy-1` stages: `[build, test, policy-test, deploy]`
  - `override-policy-2` stages: `[deploy, test]`

The pipeline fails if one or more override_project_ci policies has an invalid stages configuration.

content type

Use the content type in a policy to reference a CI/CD configuration stored in another repository. This allows you to reuse the same CI/CD configuration across multiple policies, reducing the overhead of maintaining these configurations. For example, if you have a custom secret detection CI/CD configuration you want to enforce in policy A and policy B, you can create a single YAML configuration file and reference the configuration in both policies.

Prerequisites:

• Users triggering pipelines run in those projects on which a policy containing the content type is enforced must have at minimum read-only access to the project containing the CI/CD

• In projects that enforce pipeline execution policies, users must have at least read-only access to the project that contains the CI/CD configuration to trigger the pipeline.

  In GitLab 17.4 and later, you can grant the required read-only access for the CI/CD configuration file specified in a security policy project using the content type. To do so, enable the setting Pipeline execution policies in the general settings of the security policy project. Enabling this setting grants the user who triggered the pipeline access to read the CI/CD configuration file enforced by the pipeline execution policy. This setting does not grant the user access to any other parts of the project where the configuration file is stored.

skip_ci type

Use the skip_ci keyword to specify whether users are allowed to apply the skip-ci directive to skip the pipelines. When the keyword is not specified, the skip-ci directive is ignored, preventing all users from bypassing the pipeline execution policies.

Policy scope schema

To customize policy enforcement, you can define a policy’s scope to either include, or exclude, specified projects, groups, or compliance framework labels. For more details, see Scope.

Pipeline strategies

Pipeline configuration strategy defines the method for merging the policy configuration with the project pipeline. Pipeline execution policies execute the jobs defined in the .gitlab-ci.yml file in isolated pipelines, which are merged into the pipelines of the target projects.

inject_ci

This strategy adds custom CI/CD configurations into the existing project pipeline without completely replacing the project’s original CI/CD configuration. It is suitable when you want to enhance or extend the current pipeline with additional steps, such as adding new security scans, compliance checks, or custom scripts.

Having multiple policies enabled injects all jobs additively.

When using this strategy, a project CI/CD configuration cannot override any behavior defined in the policy pipelines because each pipeline has an isolated YAML configuration.

For projects without a .gitlab-ci.yml file, this strategy will create the .gitlab-ci.yml file implicitly. That is, a pipeline containing only the jobs defined in the pipeline execution policy is executed.

override_project_ci

This strategy replaces the project’s existing CI/CD configuration with a new one defined by the pipeline execution policy. This strategy is ideal when the entire pipeline needs to be standardized or replaced, like when you want to enforce organization-wide CI/CD standards or compliance requirements in a highly regulated industry. To override the pipeline configuration, define the CI/CD jobs and do not use include:project.

The strategy takes precedence over other policies using the inject_ci strategy. If any policy with override_project_ci applies, the project CI configuration will be ignored. Other security policy configurations will not be overridden.

Alternatively, you can merge the project’s CI/CD configuration with the project’s .gitlab-ci.yml instead of overriding it. To merge the configuration, use include:project. This strategy allows users to include the project CI/CD configuration in the pipeline execution policy configuration, enabling the users to customize the policy jobs. For example, they can combine the policy and project CI/CD configuration into one YAML file to override the before_script configuration or define required variables, such as CS_IMAGE, to define the required path to the container to scan. Here’s a short demo of this behavior. The following diagram illustrates how variables defined at the project and policy levels are selected in the resulting pipeline:

Include a project’s CI/CD configuration in the pipeline execution policy configuration

When using override_project_ci strategy, the project configuration can be included into the pipeline execution policy configuration:

include:
  - project: $CI_PROJECT_PATH
    ref: $CI_COMMIT_SHA
    file: $CI_CONFIG_PATH

compliance_job:
 ...

Jobs from the project configuration that are defined for a custom stage are excluded from the final pipeline. To include a job in the final configuration, you can:

• Use stages to define custom stages in the pipeline execution policy configuration.
• Use a default pipeline stage
• Use a reserved stage (.pipeline-policy-pre or .pipeline-policy-post).

CI/CD variables

Pipeline execution jobs are executed in isolation. Variables defined in another policy or in the project’s .gitlab-ci.yml file are not available in the pipeline execution policy and cannot be overwritten from the outside.

Variables can be shared with pipeline execution policies using group or project settings. If a variable is not defined in a pipeline execution policy, the value from group or project settings is applied. If the variable is defined in the pipeline execution policy, the group or project setting is overwritten. This behavior is independent from the pipeline execution policy strategy.

You can define project or group variables in the UI.

Behavior with [skip ci]

To prevent a regular pipeline from triggering, users can push a commit to a protected branch with [skip ci] in the commit message. However, jobs defined with a pipeline execution policy are always triggered, as the policy ignores the [skip ci] directive. This prevents developers from skipping the execution of jobs defined in the policy, which ensures that critical security and compliance checks are always performed.

Interaction with scan execution policies

When you use pipeline execution policies with the override_ci strategy, be aware that this can affect the behavior of scan execution policies:

• The scan execution policy may be overridden if both pipeline execution policies and scan execution policies are configured for a project, and the pipeline execution policy uses the override_ci strategy.

This is because the override_ci strategy removes all CI/CD configuration that is defined on the project level, including policies.

To ensure that both pipeline execution policies and scan execution policies are applied:

• Consider using a different strategy for pipeline execution policies, such as inject_ci.
• If you must use override_ci, include the scanner templates that you require in your pipeline execution policy to maintain the desired security scans.

Support for improvements in the integration between these policy types is proposed in issue 504434.

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"

Customize security scanner’s behavior with before_script in project configurations

To customize the behavior of a security job enforced by a policy in the project’s .gitlab-ci.yml, you can override before_script. To do so, use the override_project_ci strategy in the policy and include the project’s CI/CD configuration. Example pipeline execution policy configuration:

# policy.yml
type: pipeline_execution_policy
name: Secret detection
description: >-
  This policy enforces secret detection and allows projects to override the
  behavior of the scanner.
enabled: true
pipeline_config_strategy: override_project_ci
content:
  include:
    - project: gitlab-org/pipeline-execution-policies/compliance-project
      file: secret-detection.yml

# secret-detection.yml
include:
  - project: $CI_PROJECT_PATH
    ref: $CI_COMMIT_SHA
    file: $CI_CONFIG_PATH
  - template: Jobs/Secret-Detection.gitlab-ci.yml

In the project’s .gitlab-ci.yml, you can define before_script for the scanner:

include:
  - template: Jobs/Secret-Detection.gitlab-ci.yml

secret_detection:
  before_script:
    - echo "Before secret detection"

By using override_project_ci and including the project’s configuration, it allows for YAML configurations to be merged.

Use group or project variables in a pipeline execution policy

You can use group or project variables in a pipeline execution policy.

With a project variable of PROJECT_VAR="I'm a project" the following pipeline execution policy job results in: I'm a project.

pipeline execution policy job:
    stage: .pipeline-policy-pre
    script:
    - echo "$PROJECT_VAR"

Enforce a variable’s value by using a pipeline execution policy

The value of a variable defined in a pipeline execution policy overrides the value of a group or policy variable with the same name. In this example, the project value of variable PROJECT_VAR is overwritten and the job results in: I'm a pipeline execution policy.

variables:
  PROJECT_VAR: "I'm a pipeline execution policy"

pipeline execution policy job:
    stage: .pipeline-policy-pre
    script:
    - echo "$PROJECT_VAR"

Example policy.yml with security policy scopes

In this example, the security policy’s policy_scope:

• Includes any project with compliance frameworks with an ID of 9 applied to them.
• Excludes projects with an ID of 456.

pipeline_execution_policy:
- name: Pipeline execution policy
  description: ''
  enabled: true
  pipeline_config_strategy: inject_ci
  content:
    include:
    - project: my-group/pipeline-execution-ci-project
      file: policy-ci.yml
  policy_scope:
    compliance_frameworks:
    - id: 9
    projects:
      excluding:
      - id: 456