Transitioning from GitLab Compliance Pipelines to Pipeline Execution Policies

The landscape of DevSecOps governance within GitLab has undergone a significant architectural shift to streamline how organizations enforce security and compliance requirements across their project portfolios. Historically, GitLab utilized compliance pipelines to ensure that specific security- and compliance-related jobs were executed in all applicable projects, regardless of whether the individual project maintainers included those jobs in their own local configurations. However, as of the 17.3 release, GitLab has officially deprecated compliance pipelines in favor of a more versatile and integrated solution known as pipeline execution policies. This evolution is not merely a renaming of features but a strategic realignment of how compliance management and policy management are handled within the platform. While compliance management focuses on visibility, reporting for auditors, and surfacing risks across the DevSecOps lifecycle, policy management is designed for the active enforcement of security and compliance mandates across the entire GitLab instance. The transition to pipeline execution policies allows users to combine the flexibility previously found in compliance pipelines with the simplicity and versatility of security policies, providing a foundation to solve for a wider array of future use cases.

The Architectural Shift and Deprecation Timeline

The decision to move away from compliance pipelines was driven by direct user feedback. Organizations required a single, simpler solution that could capture the benefits of both compliance pipelines and scan execution policies. To meet this need, GitLab introduced pipeline execution policies to enforce customized CI/CD jobs. This shift marks a clear distinction between the visibility of compliance and the enforcement of security.

The timeline for this transition is critical for all GitLab administrators and DevOps engineers to understand to avoid breaking changes in their automation workflows.

The impact of this timeline is that any organization still relying on the legacy compliance pipeline framework will face a complete loss of enforcement capabilities upon the release of version 19.0. Therefore, the migration to pipeline execution policies must be completed as soon as possible to maintain the integrity of security gates.

Pipeline Execution Policies Functional Overview

Pipeline execution policies allow for the management and enforcement of CI/CD jobs across multiple projects using a single, centralized configuration. This ensures that mandatory security scans or compliance checks are not omitted by project developers.

These policies are available under the following conditions:

• Tier: Ultimate
• Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

The technical implementation involves a YAML file consisting of an array of objects that match the pipeline execution policy schema. These objects are nested under the pipeline_execution_policy key. It is important to note that there is a hard limit on configuration: a maximum of five policies can be configured under the pipeline_execution_policy key per security policy project.

Critical Migration Warnings and Behavioral Risks

A severe operational risk exists when running both legacy compliance pipelines and the new pipeline execution policies simultaneously in the same project. GitLab explicitly warns against enabling pipeline execution policies until all existing compliance pipelines in that project have been migrated.

The conflict arises because of how the two systems interact with the project pipeline:

• Compliance pipelines replace the standard project pipeline entirely.
• Pipeline execution policies apply based on the original project pipeline.

When both are active, the resulting behavior becomes unpredictable. This inconsistency depends on the specific pipeline execution policy strategy and the individual CI/CD configurations. The real-world consequences of this overlap include:

• Duplication of jobs, where the same security scan may run twice, wasting runner resources.
• Pipeline failures caused by conflicting job definitions or overlapping stages.
• Missing critical security and compliance checks, creating a false sense of security while leaving vulnerabilities undetected.

Technical Implementation Guide for Pipeline Execution Policies

To implement a pipeline execution policy, an organization must first establish a centralized template project that houses the mandatory CI/CD logic. This prevents the duplication of code across hundreds of individual projects.

The process for establishing an enforced security scan follows these technical steps:

1. Create a central project to serve as the template.

• Navigate to the ILT group or organization group.
• Select New project.
• Select Create blank project.
• Set the project name to CICD Template.
• Finalize the project creation with default options.

2. Define the mandatory CI/CD configuration.

• Create a new file named .gitlab-ci.yml within the CICD Template project.
• Insert the configuration to enforce a SAST (Static Analysis Security Testing) scanner.

yaml stages: - test include: - component: ilt.gitlabtraining.cloud/components/sast/sast@main semgrep-sast: rules: - if: $CI_PIPELINE_SOURCE == 'merge_request_event'

3. Apply the policy to the target project.

• Navigate to the target Compliance project.
• Access the left sidebar and select Secure > Policies.
• Select New policy.
• Under the Pipeline execution policy option, select Select policy.
• Assign the name Enforce Security.
• Under the Actions section, select Inject from the CICD Template project.
• Provide the specific file path to the .gitlab-ci.yml file created in the template project.

This workflow ensures that every time a merge request event occurs in the target project, the SAST scan is automatically injected and executed, regardless of the project's own .gitlab-ci.yml content.

Managing Job Conflicts and Versioning

As GitLab transitioned through versions 17.2 and 17.3, a strict requirement was implemented regarding job names. To prevent execution errors, job names must be unique. If a pipeline execution policy injects a job with the same name as a job already present in the project's local configuration, a conflict occurs.

In GitLab 17.4, the platform introduced enhancements to manage these conflicts, providing more flexibility in how the system handles overlapping job definitions. This is critical for large-scale enterprises where individual project teams may have already implemented their own versions of a security scan that the organization is now trying to standardize via a global policy.

Integration with Broader Compliance Ecosystems

The shift toward pipeline execution policies is part of a broader strategy to separate visibility from enforcement. Compliance management tools in GitLab are designed to help organizations understand their posture and provide necessary data for auditors. This includes:

• Reporting tools for auditor review.
• Surfacing compliance risks for immediate action.
• Increasing visibility into framework requirements and violations.
• Tracking audit events across the DevSecOps lifecycle.

Additionally, for organizations requiring specialized license compliance and vulnerability management, the GitLab CI/CD ecosystem supports integration with third-party tools such as FOSSA. These integrations typically involve configuring the .gitlab-ci.yml to include FOSSA scanning jobs, which can be enforced via the same pipeline execution policies to ensure that no software is deployed without a proper license audit.

Analysis of the Transition Strategy

The migration from compliance pipelines to pipeline execution policies represents a fundamental change in how GitLab views the "Compliance as Code" paradigm. The original compliance pipeline model was an "all-or-nothing" approach where the compliance project's configuration essentially hijacked the project pipeline. While effective, this lacked the granularity needed for complex enterprise environments.

The new policy-based approach is superior because it treats security and compliance as "injected" requirements. This allows the project pipeline to remain the primary driver of the build and deploy process, while the security policy acts as an invisible guardrail. By moving the logic into the "Secure > Policies" section of the UI, GitLab has successfully decoupled the administrative intent (the policy) from the technical implementation (the CI/CD YAML).

The risk remains heavily skewed toward users who ignore the deprecation timeline. Because the removal in version 19.0 is labeled as a breaking change, the technical debt accrued by staying on the legacy system will result in a sudden failure of all compliance enforcement. The move to a five-policy maximum per project also forces organizations to be more intentional about their security architecture, preventing "policy bloat" where too many conflicting scripts slow down the overall developer velocity.

Sources

1. Why GitLab is deprecating compliance pipelines in favor of security policies
2. GitLab Compliance - Hands-On Lab: Pipeline Execution Policies
3. Pipeline execution policies
4. GitLab CI/CD: Setup, Pipeline Configuration, and FOSSA Integration