compliance

GitLab Ultimate Compliance Management

This guide covers compliance frameworks, controls, audit requirements, and evidence collection in GitLab Ultimate. Compliance management helps organizations meet regulatory requirements for SOC 2, GDPR, HIPAA, and other standards.

Overview

GitLab Ultimate provides comprehensive compliance management capabilities:

Compliance Frameworks - Pre-defined and custom frameworks (SOC 2, GDPR, HIPAA, ISO 27001)
Compliance Controls - 50+ built-in controls aligned with industry standards
Compliance Pipelines - Enforce security and quality requirements
Audit Events - Comprehensive audit trails and event streaming
Compliance Reports - Automated evidence collection and reporting
Separation of Duties - Role-based controls and approvals

Compliance Frameworks

Overview

Compliance frameworks define specific requirements for regulatory standards. GitLab supports both pre-defined frameworks and custom frameworks tailored to organizational needs.

Supported Standards

Pre-defined Frameworks:

SOC 2 - Service Organization Control 2 (security, availability, processing integrity)
GDPR - General Data Protection Regulation (EU data privacy)
HIPAA - Health Insurance Portability and Accountability Act (healthcare)
ISO 27001 - Information Security Management System
CIS Benchmarks - Center for Internet Security best practices
SOX - Sarbanes-Oxley Act (financial reporting)

Framework Focus:

GitLab's compliance management is primarily focused on:

SOC 2 (Service Organizations)
SOX (Financial Controls)
HIPAA (Healthcare)

These frameworks share fundamental requirements that benefit all compliance programs.

Creating Compliance Frameworks

Group-Level Configuration:

Compliance frameworks are managed at the group level and can be applied to multiple projects.

Steps:

Navigate to: Group > Settings > General > Compliance frameworks
Click "Add framework"
Configure framework details:
- Name (e.g., "SOC 2 Compliance")
- Description
- Compliance pipeline configuration (optional)
- Default framework (yes/no)

Example Configuration:

Name: SOC 2 Type II Compliance
Description: |
  Projects assigned this framework must comply with SOC 2 Type II requirements
  including security, availability, and confidentiality controls.

Features:
  - Required compliance pipeline
  - Security policy enforcement
  - Audit event tracking
  - Evidence collection

Controls Applied:
  - Security scanning (SAST, DAST, Dependency)
  - Code review requirements
  - Merge request approvals
  - Branch protection
  - Audit logging

Pre-defined Framework: SOC 2

SOC 2 Framework:

GitLab provides a soc2.json template to create a compliance framework for SOC 2:

SOC 2 Requirements:

Security scanning on all commits
Code review by qualified personnel
Separation of duties (no self-approval)
Audit trail of all changes
Access controls and authentication
Incident response procedures
Vulnerability management

Configuration (soc2.json):

{
  "name": "SOC 2 Type II",
  "description": "SOC 2 compliance framework for service organizations",
  "controls": [
    {
      "id": "CC6.1",
      "name": "Logical and Physical Access Controls",
      "requirements": [
        "protected_branches",
        "code_owner_approval",
        "no_push_to_protected_branches"
      ]
    },
    {
      "id": "CC7.2",
      "name": "Security and Availability Monitoring",
      "requirements": [
        "security_scanning_required",
        "dependency_scanning_required",
        "audit_events_enabled"
      ]
    },
    {
      "id": "CC8.1",
      "name": "Change Management",
      "requirements": [
        "merge_request_approval",
        "pipeline_success_required",
        "separation_of_duties"
      ]
    }
  ]
}

Applying Frameworks to Projects

Assigning Frameworks:

Navigate to: Project > Settings > General > Compliance
Select compliance framework(s) from dropdown
Save changes

Multiple Frameworks:

Projects can have up to 20 compliance frameworks applied simultaneously:

Example: Financial Services Project
- SOC 2 (Service security)
- SOX (Financial controls)
- GDPR (Customer data privacy)
- PCI DSS (Payment card data)

Framework Inheritance:

Frameworks are defined at group level
All subgroups and projects inherit available frameworks
Projects select which frameworks apply to them
Controls are enforced automatically

Compliance Controls

Overview

GitLab provides 50+ pre-defined controls aligned with SOC 2, ISO 27001, CIS Benchmarks, and other standards. Controls check project configuration and behavior against compliance requirements.

Control Types

Configuration Controls:

Protected branches enabled
Code owner approval required
Force push disabled
Merge request approval rules
Security scanning enabled
Audit events configured

Behavioral Controls:

All changes via merge requests
Successful pipeline required
Security scans passed
No critical vulnerabilities
Separation of duties enforced
Audit trail maintained

Built-in Controls

Access Controls:

Control: Protected Branches
Requirement: Default and critical branches must be protected
Check: Verifies protected branch configuration
Compliance: SOC 2 CC6.1, ISO 27001 A.9.4.5

Control: Code Owner Approval
Requirement: Changes to critical code require code owner approval
Check: Verifies CODEOWNERS file exists and approval rules configured
Compliance: SOC 2 CC6.2, SOX Section 404

Control: No Self-Approval
Requirement: Merge request author cannot approve their own MR
Check: Verifies "Prevent approval by author" setting enabled
Compliance: SOC 2 CC6.2, Separation of Duties

Security Controls:

Control: SAST Enabled
Requirement: Static application security testing must run on all commits
Check: Verifies SAST job in .gitlab-ci.yml
Compliance: SOC 2 CC7.2, ISO 27001 A.12.6.1

Control: Dependency Scanning Enabled
Requirement: All dependencies must be scanned for vulnerabilities
Check: Verifies Dependency Scanning job in .gitlab-ci.yml
Compliance: SOC 2 CC7.2, SOX Section 404

Control: No Critical Vulnerabilities
Requirement: No unresolved critical vulnerabilities allowed
Check: Verifies vulnerability count in Security Dashboard
Compliance: SOC 2 CC7.2, HIPAA 164.308(a)(1)

Change Management Controls:

Control: Merge Request Required
Requirement: All changes must go through merge request process
Check: Verifies push rules block direct commits to protected branches
Compliance: SOC 2 CC8.1, SOX Section 404

Control: Pipeline Success Required
Requirement: All pipelines must pass before merge
Check: Verifies "Pipelines must succeed" setting enabled
Compliance: SOC 2 CC8.1, ISO 27001 A.12.1.4

Control: Code Review Required
Requirement: All changes must be reviewed by qualified personnel
Check: Verifies approval rules with at least 1 approval required
Compliance: SOC 2 CC8.1, SOX Section 404

Creating Custom Controls

Custom Control Definition:

Organizations can define custom controls tailored to their requirements:

custom_controls:
  - id: CUSTOM-001
    name: "Production Deployment Approval"
    description: "Production deployments require approval from DevOps team"
    requirements:
      - type: environment_approval
        environment: production
        approvers: ["@devops-team"]
        approvals_required: 2
    compliance_mapping:
      - SOC 2 CC8.1
      - Internal Policy DEPLOY-01

  - id: CUSTOM-002
    name: "Security Team Review for IAM Changes"
    description: "Changes to authentication/authorization require security review"
    requirements:
      - type: code_owner_approval
        paths: ["app/models/user.rb", "app/controllers/sessions_controller.rb"]
        approvers: ["@security-team"]
        approvals_required: 1
    compliance_mapping:
      - SOC 2 CC6.2
      - HIPAA 164.312(a)(2)(i)

Control Verification

Compliance Dashboard:

View control status across projects:

Navigate to: Group > Security & Compliance > Compliance Report
View control compliance by project
Identify non-compliant projects
Export compliance report

Control Status:

Control: Protected Branches
Status: Compliant
Projects: 45/50 (90%)
Non-Compliant:
  - project-a (no protected branches)
  - project-b (allow force push enabled)
  - project-c (no push rules)
  - project-d (insufficient approvals)
  - project-e (code owners not required)

Compliance Pipelines

Overview

Compliance pipelines enforce security and quality requirements through CI/CD. They ensure all code changes meet compliance standards before deployment.

Configuration

Compliance Pipeline (.compliance-gitlab-ci.yml):

Create group-level compliance pipeline:

Create repository: compliance-pipeline
Add file: .compliance-gitlab-ci.yml
Configure in group settings

Example Compliance Pipeline:

# .compliance-gitlab-ci.yml
# This pipeline is injected into all projects with compliance framework

include:
  # Require all security scanners
  - 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_check
  - test
  - security_test
  - compliance_report

# Compliance checks run first
compliance_check:
  stage: compliance_check
  script:
    - echo "Running compliance checks..."
    - ./scripts/check-compliance.sh
  rules:
    - if: '$CI_MERGE_REQUEST_ID'
    - if: '$CI_COMMIT_BRANCH == "main"'

# Verify code owners file exists
verify_code_owners:
  stage: compliance_check
  script:
    - |
      if [ ! -f "CODEOWNERS" ] && [ ! -f ".gitlab/CODEOWNERS" ]; then
        echo "ERROR: CODEOWNERS file required for compliance"
        exit 1
      fi
  allow_failure: false

# Check for required approvals configuration
verify_approval_rules:
  stage: compliance_check
  script:
    - |
      # Use GitLab API to verify approval rules
      curl --header "PRIVATE-TOKEN: $API_TOKEN" \
        "$CI_API_V4_URL/projects/$CI_PROJECT_ID/approval_rules" | \
        jq -e '. | length > 0'
  allow_failure: false

# Security scans (from included templates)
sast:
  stage: test

dependency_scanning:
  stage: test

secret_detection:
  stage: test

container_scanning:
  stage: security_test
  needs: ["build"]

# Generate compliance report
compliance_report:
  stage: compliance_report
  script:
    - ./scripts/generate-compliance-report.sh
  artifacts:
    reports:
      junit: compliance-report.xml
    paths:
      - compliance-report.html
  when: always

Compliance Pipeline Enforcement

How It Works:

Compliance pipeline configured at group level
Assigned to compliance framework
Automatically injected into all projects with that framework
Runs alongside project pipeline
Project pipeline cannot override compliance pipeline

Key Features:

Cannot be disabled - Projects cannot remove compliance jobs
Cannot be modified - Project .gitlab-ci.yml cannot override compliance requirements
Always runs - Even if project has no .gitlab-ci.yml
Enforces controls - Ensures compliance requirements are met

Example Enforcement:

Project: financial-api
Framework: SOC 2 Compliance
Compliance Pipeline: soc2-compliance-pipeline

Pipeline stages:
1. compliance_check (injected from compliance pipeline)
   - verify_code_owners 
   - verify_approval_rules 
   - check_branch_protection 

2. build (project pipeline)
   - npm install 
   - npm run build 

3. test (project + compliance pipeline)
   - npm test 
   - sast (injected) 
   - dependency_scanning (injected) 

4. security_test (compliance pipeline)
   - secret_detection 
   - container_scanning 

5. compliance_report (compliance pipeline)
   - generate report 

Result: All compliance requirements met

Implicit Pipeline Creation

For Projects Without .gitlab-ci.yml:

If a project doesn't have .gitlab-ci.yml but is assigned a compliance framework:

GitLab creates .gitlab-ci.yml implicitly
Includes compliance pipeline jobs
Ensures security scans can run
Enforces compliance even without explicit CI/CD

Example:

Project: legacy-app
Status: No .gitlab-ci.yml file
Framework: HIPAA Compliance

GitLab creates implicit pipeline:
- secret_detection (scans for exposed PHI)
- sast (scans for security vulnerabilities)
- dependency_scanning (scans for vulnerable libraries)
- compliance_check (verifies HIPAA controls)

All compliance requirements enforced despite no explicit CI/CD.

Separation of Duties

Overview

Separation of Duties (SoD) ensures multiple people are involved in critical processes, preventing errors and malicious activity. It's a fundamental requirement for SOC 2, SOX, and other compliance frameworks.

Key Principles

Fundamental Rules:

No individual can complete a critical task alone
Roles best-suited for tasks are the only ones that can perform them
Processes cannot be disabled, modified, or circumvented
All actions are audited and traceable

Application to Software Development:

Code author cannot approve their own merge requests
Developers cannot deploy to production without approval
Security policies cannot be disabled by project members
Sensitive changes require additional approval

Implementing SoD in GitLab

Prevent Author Approval:

Navigate to: Settings > Merge Requests > Approval Rules
Enable: "Prevent approval by author"
Enable: "Prevent approval by merge request committers"

Require Multiple Approvals:

Approval Rule: Production Changes
- Approvals required: 2
- Eligible approvers:
  - @tech-lead-team
  - @senior-developers
- Prevent author approval: Yes
- Prevent committers approval: Yes

Code Owner Approvals:

# CODEOWNERS
# Critical code requires approval from specific teams

# Database migrations require DBA approval
db/migrate/* @dba-team

# Authentication code requires security team approval
app/models/user.rb @security-team
app/controllers/sessions_controller.rb @security-team

# Infrastructure requires DevOps approval
terraform/ @devops-team
kubernetes/ @devops-team

# API changes require architecture approval
app/api/ @architecture-team

Environment-Specific Approvals:

# Production environment approvals
Environment: production
Required Approvers:
  - @devops-team (deployment approval)
  - @product-owner (business approval)
Approvals Required: 2
Allow self-approval: No

Protected Branches and SoD

Protected Branch Configuration:

Branch: main
Allowed to merge:
  - Maintainers
  - @tech-lead-team

Allowed to push:
  - No one (force merge requests)

Allowed to force push:
  - No one (disabled)

Require approval: Yes
Approvals required: 2
Code owner approval required: Yes

Push Rules:

Navigate to: Settings > Repository > Push Rules
Configure:
- Reject unsigned commits
- Do not allow users to remove Git tags with git push
- Check whether the commit author is a GitLab user
- Require approval for merge requests

Audit Events and Compliance

Overview

Audit events provide a comprehensive trail of all actions in GitLab. They're essential for compliance, security investigations, and forensic analysis.

Audit Event Types

User Actions:

Sign in/sign out
Failed authentication attempts
Password changes
Two-factor authentication changes
Access token creation/revocation
SSH key addition/removal

Project Actions:

Project creation/deletion
Member addition/removal
Permission changes
Settings modifications
Variable changes
Protected branch changes

Code Changes:

Push to repository
Merge request creation/merge
Approval addition/removal
Pipeline execution
Deployment to environment

Security Events:

Security scan results
Vulnerability status changes
Security policy changes
Secret detection findings

Compliance Events:

Compliance framework assignment
Control status changes
Approval rule modifications
Audit configuration changes

Viewing Audit Events

Project-Level Audit Events:

Navigate to: Security & Compliance > Audit Events
View all events for project
Filter by date, event type, user

Group-Level Audit Events:

Navigate to: Group > Security & Compliance > Audit Events
View events across all projects in group
Filter and export

Instance-Level Audit Events:

Navigate to: Admin Area > Security & Compliance > Audit Events
View events across entire GitLab instance
Filter by project, group, user, event type

Audit Event Streaming

Real-Time Event Streaming (Ultimate):

Stream audit events to external systems for real-time monitoring and analysis:

Supported Destinations:

HTTP/HTTPS endpoints
Splunk
DataDog
Google Cloud Logging
Any service accepting structured JSON

Configuration:

Navigate to: Admin Area > Settings > Audit Events
Add streaming destination
Configure endpoint URL
Add custom headers (up to 20)
Enable event filtering

Example Configuration:

Streaming Destination: Splunk Infrastructure Monitoring
URL: https://splunk.example.com/services/collector
Headers:
  Authorization: "Splunk $SPLUNK_TOKEN"
  Content-Type: "application/json"
Event Filter:
  - authentication_events
  - authorization_events
  - repository_events
  - security_events

Event Format:

{
  "id": "a1b2c3d4-e5f6-4a5b-8c7d-9e8f7a6b5c4d",
  "author_id": 123,
  "author_name": "John Doe",
  "entity_id": 456,
  "entity_type": "Project",
  "details": {
    "custom_message": "Pushed to main branch",
    "target_details": "main",
    "ip_address": "192.168.1.100",
    "entity_path": "group/project"
  },
  "created_at": "2026-01-08T10:30:00.000Z",
  "event_type": "push_to_branch"
}

Audit Event Retention

Retention Policy:

GitLab Ultimate retains audit events indefinitely with no automatic deletion:

All events available for entire project/group/instance history
No time-based retention limits
Export capability for long-term archival
API access for programmatic retrieval

Export Options:

CSV Export - Export visible events (limit: 100,000)
API Export - Programmatic access to all events
Streaming - Real-time to external systems

Compliance Reporting

Compliance Center

Compliance Center Overview:

The Compliance Center provides centralized visibility into compliance status across all projects:

Navigate to: Group > Security & Compliance > Compliance Center
View compliance violations
Generate compliance reports
Track remediation progress

Compliance Violations Report

Violations Report:

Comprehensive view of compliance violations across all projects:

Information Displayed:

Violated controls
Associated projects
Severity level
Violation status (open, in progress, resolved)
Assigned owner
Due date
Associated audit events

Example Report:

Compliance Violations - Financial Services Group

Critical Violations: 3
High Violations: 8
Medium Violations: 15
Low Violations: 22

Top Violations:
1. Protected Branches Not Configured (12 projects)
   Control: SOC 2 CC6.1
   Severity: High
   Status: 8 in progress, 4 open

2. SAST Not Enabled (8 projects)
   Control: SOC 2 CC7.2
   Severity: High
   Status: 5 in progress, 3 open

3. Code Owner Approval Not Required (15 projects)
   Control: SOC 2 CC6.2
   Severity: Medium
   Status: 10 in progress, 5 open

Managing Violation Status

Status Workflow:

Open  In Progress  Resolved
     
     Accepted Risk (with justification)

Updating Status:

Open compliance violation
Review details and requirements
Update status
Add comment with justification
Assign to responsible team member
Set due date

Example Status Update:

Violation: SAST Not Enabled
Project: legacy-api
Control: SOC 2 CC7.2
Severity: High

Status: In Progress
Assigned: @dev-team-lead
Due Date: 2026-01-15

Comment:
SAST configuration is being added to .gitlab-ci.yml.
Template has been tested in feature branch.
Merge request #123 will enable SAST for all future commits.
Expected completion: 2026-01-12

Evidence Collection

Compliance Evidence:

GitLab automatically collects evidence for compliance audits:

Evidence Types:

Security scan results
Approval records
Audit event logs
Pipeline execution records
Vulnerability remediation timeline
Access control configurations
Code review documentation

Exporting Evidence:

Security Scan Results
- Download from pipeline artifacts
- Export from Vulnerability Report
- API access for automation
Audit Events
- CSV export (up to 100,000 events)
- API export (unlimited)
- Streaming to external systems
Approval Records
- Merge request approval history
- Environment deployment approvals
- Security policy approvals
Compliance Reports
- Generate from Compliance Center
- Export as PDF/CSV
- Include in audit documentation

Compliance Report Generation

Automated Reports:

Generate compliance reports for auditors:

# Export audit events
curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  "https://gitlab.com/api/v4/groups/123/audit_events?created_after=2025-01-01&created_before=2025-12-31" \
  > audit_events_2025.json

# Export compliance violations
curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  "https://gitlab.com/api/v4/groups/123/compliance/violations" \
  > compliance_violations.json

# Export security findings
curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  "https://gitlab.com/api/v4/projects/456/vulnerabilities?created_after=2025-01-01" \
  > security_findings_2025.json

Report Contents:

SOC 2 Type II Compliance Report - 2025

1. Executive Summary
   - Compliance status overview
   - Control effectiveness
   - Key achievements
   - Areas for improvement

2. Control Assessment
   - CC6.1: Logical Access Controls - Compliant
   - CC6.2: Prior to Issuing Credentials - Compliant
   - CC7.2: System Monitoring - Compliant
   - CC8.1: Change Management - Compliant

3. Security Scanning Results
   - Total scans: 1,847
   - Vulnerabilities detected: 284
   - Vulnerabilities resolved: 276
   - Mean time to remediation: 12 days

4. Access Controls
   - Protected branches: 100% of projects
   - Code owner approval: 98% of projects
   - Separation of duties: Enforced

5. Audit Trail
   - Audit events collected: 45,892
   - All events retained indefinitely
   - Real-time streaming enabled

6. Evidence Appendix
   - Audit event logs (attached)
   - Security scan results (attached)
   - Approval records (attached)
   - Violation remediation timeline (attached)

Best Practices

Framework Implementation

Start with One Framework - Implement SOC 2 first, expand to others
Pilot with Small Group - Test with non-critical projects first
Document Requirements - Clearly define each control requirement
Train Teams - Educate developers on compliance requirements
Monitor Compliance - Review compliance status weekly

Control Configuration

Leverage Built-in Controls - Use GitLab's 50+ pre-defined controls
Customize as Needed - Add organization-specific controls
Automate Checks - Use compliance pipelines for automated verification
Regular Audits - Review control effectiveness quarterly
Remediate Violations - Address compliance violations promptly

Audit Preparation

Enable Audit Event Streaming - Stream to external systems for retention
Document Processes - Maintain compliance documentation
Collect Evidence Proactively - Don't wait for audit requests
Regular Exports - Export audit events monthly
Mock Audits - Conduct internal audits before external ones

Team Coordination

Assign Compliance Owners - Designate compliance champions
Regular Reviews - Review compliance status in team meetings
Clear Communication - Explain why controls exist
Support Developers - Provide tools and guidance
Celebrate Success - Recognize compliance achievements

Troubleshooting

Common Issues

Framework not enforcing controls:

Verify framework assigned to project
Check compliance pipeline configuration
Ensure security policies are enabled
Verify group-level settings

Compliance violations not showing:

Wait for next pipeline run
Verify controls are properly configured
Check group-level access permissions
Review control definitions

Audit events missing:

Verify audit event retention settings
Check date range filters
Ensure proper permissions
Verify event type filters

Compliance pipeline not running:

Verify compliance framework assignment
Check pipeline configuration at group level
Ensure compliance repository exists
Review .compliance-gitlab-ci.yml syntax

References

Next Steps

Security Policies - Enforce security requirements
Access Control - Configure branch protection and approvals
Vulnerability Management - Track and remediate issues