GitLab Compliance Frameworks & Mandatory Pipeline Prompt

You are a senior platform engineer in a regulated industry (SOX, SOC 2, ISO 27001, PCI, HIPAA) who has built compliance enforcement via GitLab Compliance Frameworks. You know how to enforce mandatory pipeline steps without allowing developers to bypass.

I will provide:
- The compliance regime (SOX, SOC 2, PCI, HIPAA, ISO 27001, custom)
- The current enforcement mechanism (none, copy-paste includes, manual review)
- GitLab tier (Compliance Frameworks require Premium+; mandatory pipeline config is Ultimate)
- The mandatory steps (SAST, dep scan, license check, signing, approval, evidence collection)

Your job:

1. **Understand the model**:
   - **Compliance Framework** (Premium+) — a label applied to projects; defines a name and description; can be required
   - **Mandatory Pipeline Configuration** (Ultimate) — the framework points to a `.gitlab-ci.yml` in another project; this config is INCLUDED automatically in every pipeline run by projects with that framework
   - Developers can't remove the mandatory config — it's enforced server-side
2. **Design the mandatory pipeline**:
   - Security scanning (SAST, secret detection, dependency scan)
   - License compliance
   - Approval gates for production
   - Signing / attestation generation
   - Audit log emission
   - Evidence artifact upload
   - The mandatory config is in a separate project; framework references its file path
3. **For evidence collection**:
   - Each pipeline produces artifacts that auditors can inspect
   - Sign artifacts (cosign, sigstore)
   - Push to an audit repository / WORM storage
   - Include commit SHA, timestamp, approver list
4. **For approval enforcement**:
   - Combined with protected environments
   - The mandatory pipeline can include a manual approval job that requires specific approvers
   - Approvers logged in audit events (Premium+)
5. **For separation of duties**:
   - Developer ≠ approver: protected environment with `required_approval_count`
   - Builder ≠ deployer: protected environments split per stage
   - Pipeline trigger ≠ deploy executor: tokens scoped narrowly
6. **For audit-ready logs**:
   - Audit events (Ultimate): every change recorded
   - Pipeline metadata captured per run
   - Stream to SIEM (Splunk, ELK, Datadog) via audit event streaming
7. **For framework application**:
   - Apply at group level: all sub-projects inherit
   - Or per-project labeling
   - Compliance Dashboard shows projects per framework
8. **For testing the framework**:
   - Test project with framework applied
   - Verify mandatory steps run AND can't be bypassed
   - Confirm audit events emitted

Mark DESTRUCTIVE: removing framework from a project under audit (loses enforcement window), allowing emergency bypass without compensating control, framework changes without staging.

---

Compliance regime: [DESCRIBE]
GitLab tier: [Premium / Ultimate]
Mandatory steps required: [DESCRIBE]
Current enforcement: [none / includes / manual]
Goal: [design framework / harden / debug]

Why this prompt works

Compliance frameworks formalize what teams often handle ad-hoc. Properly implemented, they remove “did the team run SAST?” from the auditor’s checklist by enforcing at the platform level.

How to use it

1. Map compliance controls to pipeline steps explicitly.
2. Implement in a separate project with strict access.
3. Apply at group level for inheritance.
4. Audit periodically that the framework is still applied.

Useful commands

# List compliance frameworks (group)
curl --header "PRIVATE-TOKEN: <t>" \
    "https://gitlab.example.com/api/v4/groups/<id>/compliance_frameworks" | jq

# Create a compliance framework
curl --request POST --header "PRIVATE-TOKEN: <t>" --header "Content-Type: application/json" \
    --data '{
        "name": "SOC2 Type II",
        "description": "SOC 2 Type II controls",
        "color": "#FF0000",
        "pipeline_configuration_full_path": "/compliance/soc2-pipeline/main/.gitlab-ci.yml@compliance/soc2-pipeline"
    }' \
    "https://gitlab.example.com/api/v4/groups/<id>/compliance_frameworks"

# Apply framework to a project
curl --request PUT --header "PRIVATE-TOKEN: <t>" --header "Content-Type: application/json" \
    --data '{"compliance_framework_id": <framework-id>}' \
    "https://gitlab.example.com/api/v4/projects/<id>"

Mandatory pipeline pattern

# In project: compliance/soc2-pipeline, file: .gitlab-ci.yml

include:
- template: Security/SAST.gitlab-ci.yml
- template: Security/Dependency-Scanning.gitlab-ci.yml
- template: Security/Secret-Detection.gitlab-ci.yml
- template: Security/Container-Scanning.gitlab-ci.yml

stages:
- compliance-scan
- audit
- developer-pipeline       # placeholder for the project's own stages

# Each project's own jobs inherit these stages

mandatory-license-check:
  stage: compliance-scan
  image: alpine
  script:
    - apk add --no-cache git curl
    - ./check-licenses.sh
  rules:
    - if: $CI_PIPELINE_SOURCE != "schedule"

mandatory-audit-log:
  stage: audit
  script:
    - |
      cat > audit-event.json <<EOF
      {
        "project_id": "$CI_PROJECT_ID",
        "pipeline_id": "$CI_PIPELINE_ID",
        "commit_sha": "$CI_COMMIT_SHA",
        "user": "$GITLAB_USER_LOGIN",
        "timestamp": "$(date -Iseconds)",
        "compliance_framework": "SOC2"
      }
      EOF
    - curl -X POST -H "Content-Type: application/json" \
        -d @audit-event.json \
        $AUDIT_SINK_URL
  rules:
    - if: $CI_PIPELINE_SOURCE != "schedule"

mandatory-evidence:
  stage: audit
  script:
    - mkdir -p evidence/
    - echo "Commit: $CI_COMMIT_SHA" > evidence/commit.txt
    - echo "Approvers: ..." > evidence/approvers.txt
    - tar czf evidence.tar.gz evidence/
    - cosign sign-blob --key $SIGNING_KEY evidence.tar.gz > evidence.tar.gz.sig
    - aws s3 cp evidence.tar.gz s3://compliance-evidence/$CI_PROJECT_PATH/$CI_PIPELINE_ID/
    - aws s3 cp evidence.tar.gz.sig s3://compliance-evidence/$CI_PROJECT_PATH/$CI_PIPELINE_ID/
  artifacts:
    paths: [evidence.tar.gz, evidence.tar.gz.sig]
    expire_in: 7 years        # SOX retention

Production deployment with separation of duties

# In compliance pipeline:
deploy-production:
  stage: developer-pipeline
  script: ./deploy.sh
  environment:
    name: production
    deployment_tier: production
  rules:
    - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/
      when: manual
  # Protected environment requires:
  #   - 2 approvals
  #   - Approver != Author (separation of duties)
  #   - Approver in "production-approvers" group

Application across a group

# Apply framework to all projects in a group
for PROJ in $(curl -s --header "PRIVATE-TOKEN: $TOKEN" \
    "$GITLAB/api/v4/groups/<id>/projects?per_page=100&include_subgroups=true" | jq -r '.[].id'); do
    curl -X PUT --header "PRIVATE-TOKEN: $TOKEN" --header "Content-Type: application/json" \
        --data "{\"compliance_framework_id\": <fw-id>}" \
        "$GITLAB/api/v4/projects/$PROJ"
done

Compliance dashboard usage

• Group → Security & Compliance → Compliance Dashboard
• Shows: pipeline status per project, frameworks applied, recent commits
• Auditors can self-serve

Common findings this catches

• Framework applied but mandatory pipeline never runs → check the pipeline_configuration_full_path syntax; must be <file>@<project>.
• Bypass via excluding the mandatory file → impossible in Ultimate; mandatory pipeline is server-merged.
• Mandatory pipeline secrets leaking to all consumers → use Vault/secret-manager pulls, not variables.
• Performance impact of mandatory scans → split into MR-only (light) and scheduled (heavy).
• Audit event sink unreachable → mandatory pipeline fails; have retry + fallback.
• Framework not enforced on schedules → check rules; schedules may need separate handling.

When to escalate

• Compliance regime change requiring new control — re-design framework with stakeholders.
• Auditor finding about insufficient evidence — improve evidence collection in mandatory pipeline.
• Performance regression from mandatory pipeline overhead — tune; split heavy steps.