How to set up a Pipeline Execution Policy with inject_policy custom CI/CD jobs

Description

Pipeline execution policies allow you to enforce and manage CI/CD configurations across projects without modifying each project's individual .gitlab-ci.yml file. This guide sets up a pipeline execution policy that can inject custom CI/CD jobs into multiple target projects from a central location. Using centrally managed pipeline execution policies provides several benefits:

Enforce consistent CI/CD jobs across multiple projects.
Update CI/CD configurations for many projects from a single location.
Ensure compliance requirements are met across your organization.
Apply CI/CD best practices without requiring individual project modifications.

This approach is particularly useful for security and compliance teams who need to enforce standardized jobs or checks across multiple projects.

Environment

Available in offerings:

GitLab.com
GitLab Dedicated
GitLab Self-Managed

Available versions:

GitLab 17.9 and later

Prerequisites

Ability to create and manage security policies (typically requires Owner or Maintainer role).
Ability to create projects and manage CI/CD configurations.

Solution

A high level overview

To implement a pipeline execution policy, you need the following components:

A security policy project to define and manage the pipeline execution policy
A CI configuration YAML file containing the job/s to be injected
Target projects where the CI/CD jobs will be enforced

The process works as follows:

You create a CI/CD configuration YAML file in the central Security Policy Project
You then define a Pipeline Execution Policy in the Security Policy Project that references this configuration file
When pipelines run in target projects, the custom CI/CD jobs from your configuration file are automatically injected

Part One - Create the Security Policy Project and configuration CI/CD file

Create a Security Policy Project to store your CI/CD configuration file. For this guide, it will be called my-org - Security Policy Project in a group called my-org.
Create a file called custom-job.yaml in this project with the following content:

custom-compliance-job:
  stage: .pipeline-policy-pre
  script:
    - echo "Running custom compliance check from centralized configuration"
    - echo "This job is enforced by a pipeline execution policy"
  rules:
    - when: always

Open the Settings > General > Visibility, project features, permissions menu
Locate and tick the box to allow target projects to access the CI/CD configuration file:

Pipeline execution policies [ ] Grant access to the CI/CD configurations for projects linked to this security policy project as the source for security policies.

Allow users and tokens read-only access to fetch security policy configurations in this project to enforce policies.

Save changes.

Note: Using the .pipeline-policy-pre stage ensures the job runs at the beginning of the pipeline before any other stages. The rules: dictates what conditions are required for the job to be put in the pipeline. when: always means that every pipeline in every project the policy targets will have the job injected.

Part Two - Create the Pipeline Execution Policy

Navigate to the my-org group
Open the Secure > Policies page for the group
Select New Policy and create a Pipeline Execution Policy
Apply the policy to the target project. For this example, the project is my-org/target-project

---
pipeline_execution_policy:
- name: Custom Compliance Job Policy
  description: Enforces a custom compliance job in all target projects
  enabled: true
  pipeline_config_strategy: inject_policy
  content:
    include:
      - project: my-org/my-org-security-policy-project
        file: custom-job.yaml
  type: pipeline_execution_policy
  policy_scope:
    projects:
      including:
        - id: 154

Note: The inject_policy strategy adds the custom job to target projects without replacing their existing CI/CD configurations.

Part Four - Customize the policy scope

The policy scope determines which projects the pipeline execution policy applies to. You can scope by projects, groups, or compliance framework labels.

To modify the policy scope:

Edit the policy.yml file in your security policy project.
Update the policy_scope section to include or exclude specific projects, groups, or compliance frameworks:

  policy_scope:
    projects:
      including:
      - id: 123
      - id: 456
      excluding:
      - id: 789
    groups:
      including:
      - id: 42
    compliance_frameworks:
      - id: 5

Verification

To verify that your pipeline execution policy is working correctly:

Navigate to one of your target projects.
Trigger a new pipeline by making a commit or manually running a pipeline.
In the pipeline view, you should see the custom-compliance-job running in the .pipeline-policy-pre stage.

If the policy is correctly applied, the job will run automatically in all pipelines for the target projects, regardless of their individual CI/CD configurations.

Additional Information

Pipeline configuration strategies

The pipeline_config_strategy determines how the policy's CI/CD configuration interacts with the project's own configuration:

inject_policy: Adds custom CI/CD jobs to the existing project pipeline without replacing the project's original CI/CD configuration.
override_project_ci: Completely replaces the project's CI/CD configuration with the one defined in the policy.

Job stage best practices

When defining jobs in a pipeline execution policy, you can use the following reserved stages to ensure your jobs run at specific points:

.pipeline-policy-pre: Runs at the beginning of the pipeline, before the .pre stage.
.pipeline-policy-post: Runs at the very end of the pipeline, after the .post stage.

These reserved stages are always available, regardless of the project's CI/CD configuration.

Job naming best practices

To avoid naming conflicts with existing jobs in target projects, use unique prefixes or suffixes for your policy jobs:

Good: policy:custom-compliance-job or custom-compliance-job:policy
Avoid: test or build (generic names likely to cause conflicts)

If job names conflict, the pipeline execution policy will handle this by adding a suffix to the job name.