Compliance Pipelines, Pipeline Execution Policies, Governance, Audit Evidence, and Enterprise Controls: Concepts, Architecture, and Mental Model

1. The problem: a project pipeline is not an organization policy

A normal .gitlab-ci.yml answers what one project wants to run. Governance asks a different question: what must run even when the project would prefer not to run it, who is allowed to change that requirement, and what evidence proves which policy version was in force? Chapter 35 optimized latency and cost. Chapter 36 adds a control plane above that optimized pipeline.

Without a visible policy origin, a green pipeline can be misleading. A project could remove a scan, run on an unapproved runner, override a policy variable, or depend on a waiver that never expires. The remedy is not “more YAML.” It is a chain of versioned policy, explicit scope, effective configuration, execution evidence, and reviewable exceptions.

2. Name the states before changing them

3. Mental model: policy intent becomes pipeline evidence

Read the chain left to right. An organization or group chooses a control objective. Authorized maintainers encode it in a security policy project. The policy references a versioned CI configuration. During pipeline creation, GitLab determines whether the target project is in scope and combines or replaces configuration according to the selected strategy. Only then do jobs enter the project pipeline. An enforced job produces evidence; audit events record governance actions; any exception must have a separate lifecycle.

The arrows matter. A policy file in Git is not evidence that it applied to a particular pipeline. A job named policy:governance-proof is not evidence of policy origin unless you can tie it to the policy project/version. An audit event saying “policy changed” is not by itself the compiled pipeline. The operating model needs all of those links.

            flowchart TD
             A[Organization or group control objective] --> B[Security policy project
            policy.yml + version]
             B --> C[Policy scope + strategy
            include / exclude]
             C --> D[Pipeline compilation
            project config + enforced config]
             D --> E[Project pipeline
            policy and project jobs]
             E --> F[Enforced gate + evidence]
             F --> G[Audit event + evidence packet]
             G --> H[Exception review
            owner + reason + expiry]
             H --> C
          

4. The vocabulary that prevents category mistakes

5. Inspect first: prove the current state without mutation

On a real authorized GitLab environment, begin with read-only observations. The exact permissions and paid features vary, so the free path later reproduces the evidence model locally.

# Project source identity
printf 'project=%s\nref=%s\nsha=%s\nsource=%s\n' \
  "$CI_PROJECT_PATH" "$CI_COMMIT_REF_NAME" "$CI_COMMIT_SHA" "$CI_PIPELINE_SOURCE"

# Optional API observations: keep the token in an environment variable; never echo it.
export GITLAB_URL="https://gitlab.example.test"
export PROJECT_ID="123456"
# export GITLAB_TOKEN="..."   # authorized, narrow, disposable only
curl --fail --silent --show-error \
  --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  "$GITLAB_URL/api/v4/projects/$PROJECT_ID/pipelines?per_page=5" | jq .

# CI Lint is available on all tiers and can validate project-side YAML.
jq --null-input --arg yaml "$(cat .gitlab-ci.yml)" '{content:$yaml,dry_run:false,include_jobs:true}' \
  | curl --fail --silent --show-error \
      --header 'Content-Type: application/json' \
      --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
      --data @- \
      "$GITLAB_URL/api/v4/projects/$PROJECT_ID/ci/lint" | jq .

CI Lint proves the supplied project configuration and its includes in project context. Do not label that result “the effective enterprise policy” unless the inspected mechanism actually includes the applied policy. For a governed pipeline, also inspect the policy project/ref, policy page, actual pipeline/job graph, policy job trace, and audit evidence.

6. Current policy behavior that changes design decisions

7. Minimal evidence chain for one governed pipeline

That chain deliberately contains both configuration and execution. If a reviewer cannot answer “which policy revision affected pipeline 8421?” without guessing, the evidence model is incomplete.

8. Governance boundaries: what a policy does not magically prove

A policy can inject or control jobs, but it cannot make every runner trustworthy, turn a plaintext repository into a secret store, or prove a deployment target is healthy. Runner approval still depends on runner scope/tags/protection and executor isolation. Secrets still need protected variables or an external secret provider. Deployment authorization remains separate from build evidence. External systems still require independent verification.

9. Where legacy compliance pipelines fit now

Compliance pipelines historically centralized project pipeline configuration through compliance frameworks. They are now deprecated. The current deprecation notice points users to pipeline execution policies and schedules removal in the GitLab 20.0 line; older migration text can still mention earlier removal targets. Treat the deprecation page for your deployed release as authoritative.

The migration lesson is broader than a product rename: inventory the old compliance framework, preserve an example pipeline and its evidence, create the new policy, compare effective jobs and variable behavior, then remove the old mechanism. Never enable both and assume they compose cleanly; GitLab explicitly warns that mixed enforcement can create duplicated, missing, or failing jobs.

10. Lesson summary

Enterprise CI/CD governance is a traceability problem as much as an enforcement problem. The object you govern is not just YAML; it is the relationship among policy source, scope, compiled configuration, pipeline, job/runner identity, evidence, audit record, and exception lifecycle. Lesson 2 turns that model into a disposable workflow.

Knowledge check

Official references and version notes

Further reading — current official GitLab sources

Behavior and tier assumptions in this chapter were checked against the current documentation on 2026-09-13. Re-check these pages before applying the optional enterprise path because policy schemas and product tiers evolve.

• GitLab Docs — Pipeline execution policies
• GitLab Docs — Security policy projects
• GitLab Docs — Policy enforcement and separation of duties
• GitLab Docs — Compliance pipelines (deprecated)
• GitLab Docs — CI/CD variables and precedence
• GitLab Docs — CI Lint API
• GitLab Docs — Audit events
• GitLab Docs — Audit events API
• GitLab Docs — Compliance frameworks
• GitLab Docs — Deprecations and removals

Current assumptions used in this chapter: Version-sensitive YAML, Runner/executor behavior, APIs, security features, policy controls, tiers, and deprecations must be verified against the exact GitLab, GitLab Runner, tool, and external-system versions used in production. Preserve the exact project/ref/SHA, compiled configuration, pipeline/job IDs, runner/tool versions, and external target evidence used for reproducible work.