Compliance frameworks

{{< details >}}

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

{{< /details >}}

You can create a compliance framework that is a label to identify that your project has certain compliance requirements or needs additional oversight.

In the Ultimate tier, the compliance framework can optionally enforce compliance pipeline configuration and security policies to the projects on which it is applied.

Compliance frameworks are created on top-level groups. If a project is moved outside of its existing top-level group, its frameworks are removed.

You can apply up to 20 compliance frameworks to each project.

For a click-through demo, see Compliance frameworks.

Prerequisites

  • To create, edit, and delete compliance frameworks, users must have either:
  • To add or remove a compliance framework to or from a project, the group to which the project belongs must have a compliance framework.

Create, edit, or delete a compliance framework

You can create, edit, or delete a compliance framework from a compliance framework report. For more information, see:

You can create, edit, or delete a compliance framework from a compliance projects report. For more information, see:

Subgroups and projects have access to all compliance frameworks created on their top-level group. However, compliance frameworks cannot be created, edited, or deleted by using subgroups or projects. Project owners can choose a framework to apply to their projects.

Apply a compliance framework to a project

{{< history >}}

  • Applying multiple compliance frameworks introduced in GitLab 17.3.
  • Applying a compliance framework to a project through a compliance framework introduced in GitLab 17.11.

{{< /history >}}

You can apply multiple compliance frameworks to a project but cannot apply compliance frameworks to projects in personal namespaces.

To apply a compliance framework to a project, apply the compliance framework through the Compliance projects report.

You can use the GraphQL API to apply one or many compliance frameworks to a project.

If you create compliance frameworks on subgroups with GraphQL, the framework is created on the root ancestor if the user has the correct permissions. The GitLab UI presents a read-only view to discourage this behavior.

To apply a compliance framework to a project through a compliance framework:

  1. On the left sidebar, select Search or go to and find your group.
  2. Select Secure > Compliance center.
  3. On the page, select the Projects tab.
  4. Hover over a compliance framework, select the Edit Framework tab.
  5. Select Projects section.
  6. Select projects from the list.
  7. Select Update Framework.

Default compliance frameworks

{{< history >}}

{{< /history >}}

Group owners can set a default compliance framework. The default framework is applied to all the new and imported projects that are created in that group. It does not affect the framework applied to the existing projects. The default framework cannot be deleted.

A compliance framework that is set to default has a default label.

Set and remove a default by using the compliance center

To set as default (or remove the default) from compliance projects report:

  1. On the left sidebar, select Search or go to and find your group.
  2. Select Secure > Compliance center.
  3. On the page, select the Projects tab.
  4. Hover over a compliance framework, select the Edit Framework tab.
  5. Select Set as default.
  6. Select Save changes.

To set as default (or remove the default) from compliance framework report:

  1. On the left sidebar, select Search or go to and find your group.
  2. Select Secure > Compliance center.
  3. On the page, select the Frameworks tab.
  4. Hover over a compliance framework, select the Edit Framework tab.
  5. Select Set as default.
  6. Select Save changes.

Remove a compliance framework from a project

To remove a compliance framework from one or multiple project in a group, remove the compliance framework through the Compliance projects report.

Import and export compliance frameworks

{{< history >}}

{{< /history >}}

Download existing compliance frameworks as JSON files and upload new frameworks from JSON templates.

A library of JSON templates is available from the Compliance Adherence Templates project. Use these templates to quickly adopt predefined compliance frameworks.

Export a compliance framework as a JSON file

With this feature, you can share and back up compliance frameworks.

To export a compliance framework from the compliance center:

  1. On the left sidebar, select Search or go to and find your group.
  2. Select Secure > Compliance center.
  3. On the page, select the Frameworks tab.
  4. Locate the compliance framework you wish to export.
  5. Select the vertical ellipsis ({{< icon name=”ellipsis_v” >}}).
  6. Select Export as JSON file.

The JSON file is downloaded to your local system.

Import a compliance framework from a JSON file

With this feature, you can use shared or backed up compliance frameworks.

To import a compliance framework by using a JSON template:

  1. On the left sidebar, select Search or go to and find your group.
  2. Select Secure > Compliance center.
  3. On the page, select the Frameworks tab.
  4. Select New framework.
  5. Select Import framework.
  6. In the dialog that appears, select the JSON file from your local system.

If the import is successful, the new compliance framework appears in the list. Any errors are displayed for correction.

Requirements

{{< details >}}

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

{{< /details >}}

{{< history >}}

  • Introduced in GitLab 17.11 with a flag named enable_standards_adherence_dashboard_v2. Disabled by default.

{{< /history >}}

In GitLab Ultimate, you can define specific requirements for a compliance framework. Requirements are made up of one or more controls, which are checks against the configuration or behavior of projects that are assigned the framework. There is maximum of 5 controls per requirement.

Controls

Each control includes logic that GitLab uses during scheduled or triggered scans to evaluate a project’s adherence. For more details on how adherence is tracked, see Compliance status report.

GitLab controls

The following controls are available to use in framework requirements:

GitLab compliance controls

GitLab compliance controls can be used in GitLab compliance frameworks. Controls are checks against the configuration or behavior of projects that are assigned to a compliance framework.

Control name Control ID Description
API security running scanner_api_security_running Ensures that API security scanning is configured and running in the project pipelines.
At least two approvals minimum_approvals_required_2 Ensures that merge requests require at least two approvals before merging.
Auth SSO enabled auth_sso_enabled Ensures that Single Sign-On (SSO) authentication is enabled for the project.
Author approved merge request merge_request_prevent_author_approval Ensures that the author of a merge request cannot approve their own changes.
Branch deletion disabled branch_deletion_disabled Ensures that branches can’t be deleted.
CI/CD job token scope enabled cicd_job_token_scope_enabled Ensures that CI/CD job token scope restrictions are enabled.
Code changes requires code owners code_changes_requires_code_owners Ensures that code changes require approval from code owners.
Code quality running scanner_code_quality_running Ensures that code quality scanning is configured and running in the project pipelines.
Committers approved merge request merge_request_prevent_committers_approval Ensures that users who have committed to a merge request cannot approve it.
Container scanning running scanner_container_scanning_running Ensures that container scanning is configured and running in the project pipelines.
DAST running scanner_dast_running Ensures that Dynamic Application Security Testing (DAST) is configured and running in the project pipelines.
Default branch protected default_branch_protected Ensures that the default branch has protection rules enabled.
Default branch protected from direct push default_branch_protected_from_direct_push Prevents direct pushes to the default branch.
Default branch users can merge default_branch_users_can_merge Controls whether users can merge changes to the default branch.
Default branch users can push default_branch_users_can_push Controls whether users can push directly to the default branch.
Dependency scanning running scanner_dep_scanning_running Ensures that dependency scanning is configured and running in the project pipelines.
Ensure two administrators per repository ensure_2_admins_per_repo Ensures that at least two administrators are assigned to each repository.
Error tracking enabled error_tracking_enabled Ensures that error tracking is enabled for the project.
Force push disabled force_push_disabled Prevents force pushing to repositories.
Fuzz testing running scanner_fuzz_testing_running Ensures that fuzz testing is configured and running in the project pipelines.
GitLab license level Ultimate gitlab_license_level_ultimate Ensures that the GitLab instance is using an Ultimate license.
Has valid CI/CD configuration has_valid_ci_config Ensures that the project has a valid CI/CD configuration.
IaC scanning running scanner_iac_running Ensures Infrastructure as Code (IaC) scanning is configured and running in the project pipelines.
Internal visibility is forbidden project_visibility_not_internal Ensures that projects are not set to internal visibility.
Issue Tracking Enabled issue_tracking_enabled Ensures that issue tracking is enabled for the project.
License Compliance Running scanner_license_compliance_running Ensures that license compliance scanning is configured and running in the project pipelines.
Merge Request Commit Reset Approvals merge_request_commit_reset_approvals Ensures that new commits to merge requests reset approvals.
Merge Requests Approval Rules Prevent Editing merge_requests_approval_rules_prevent_editing Ensures that merge request approval rules can’t be edited.
Merge Requests Require Code Owner Approval merge_requests_require_code_owner_approval Ensures that merge requests require approval from code owners.
Minimum Number of Admins minimum_number_of_admins Ensures a minimum number of administrators are assigned to the project.
Package Hunter No Findings Untriaged package_hunter_no_findings_untriaged Ensures that all Package Hunter findings are triaged.
Project Archived project_archived Checks whether the project is archived. Typically false is compliant.
Project Marked For Deletion project_marked_for_deletion Checks whether the project is marked for deletion. false is compliant.
Project Pipelines Not Public project_pipelines_not_public Ensures that project pipelines are not publicly visible.
Project User Defined Variables Restricted To Maintainers project_user_defined_variables_restricted_to_maintainers Ensures that only maintainers can create project variables.
Project Visibility Not Public project_visibility_not_public Ensures that projects are not set to public visibility.
Push Protection Enabled push_protection_enabled Ensures that push protection is enabled for sensitive files.
Require Branch Up to Date require_branch_up_to_date Ensures that the source branch is up to date with the target branch before merging.
Require Linear History require_linear_history Ensures a linear commit history by forbidding merge commits.
Require MFA at Org Level require_mfa_at_org_level Ensures that multi-factor authentication is required at the organization level.
Require MFA for Contributors require_mfa_for_contributors Ensures that contributors have multi-factor authentication enabled.
Reset Approvals on Push reset_approvals_on_push Ensures that approvals are reset when new commits are pushed to the merge request.
Resolve Discussions Required resolve_discussions_required Ensures that all discussions must be resolved before merging is allowed.
Restrict Push/Merge Access restrict_push_merge_access Restricts who can push to or merge into protected branches.
Restricted Build Access restricted_build_access Ensures restricted access to build artifacts and pipeline outputs.
Review and Archive Stale Repositories review_and_archive_stale_repos Ensures that stale repositories are reviewed and archived.
Review and Remove Inactive Users review_and_remove_inactive_users Ensures that inactive users are reviewed and removed.
SAST Running scanner_sast_running Ensures that Static Application Security Testing (SAST) is configured and running in the project pipelines.
Secret Detection Running scanner_secret_detection_running Ensures that secret detection scanning is configured and running in the project pipelines.
Secure Webhooks secure_webhooks Ensures that webhooks are securely configured.
Stale Branch Cleanup Enabled stale_branch_cleanup_enabled Ensures that automatic cleanup of stale branches is enabled.
Status Checks Required status_checks_required Ensures that status checks must pass before merging is allowed.
Status Page Configured status_page_configured Ensures that a status page is configured for the project.
Strict Permission for Repository strict_permissions_for_repo Ensures that strict permissions are set for repository access.
Terraform Enabled terraform_enabled Ensures that the Terraform integration is enabled for the project.
Version Control Enabled version_control_enabled Ensures that version control is enabled for the project.
Vulnerabilities SLO Days Over Threshold vulnerabilities_slo_days_over_threshold Ensures that vulnerabilities are addressed inside SLO thresholds.

External controls

External controls are API calls to external systems that request the status of an external control or requirement.

You can create a external control that sends data to third-party tools.

When the compliance scans are run, GitLab sends a notification. The users or automated workflows can then update the status of control from outside of GitLab.

With this integration, you can integrate with third-party workflow tools, like ServiceNow, or the custom tool of your choice. The third-party tool responds with an associated status. This status is then displayed in the Compliance status report.

You can configure external controls for each individual project. External controls are not shared between projects. Status checks fail if an external control stays in the pending state for more than six hours.

Add external controls

To add an external control when creating or editing a framework:

  1. On the left sidebar, select Search or go to and find your group.
  2. Select Secure > Compliance center.
  3. On the page, select the Frameworks tab.
  4. Select New framework or edit an existing one.
  5. In the Requirements section, select New requirement.
  6. Select Add an external control.
  7. In the fields edit External URL and HMAC shared secret.
  8. Select Save changes to the framework to save the requirement.

External control lifecycle

External controls have an asynchronous workflow. Compliance scans emit a payload to an external service whenever.

sequenceDiagram GitLab->>+External service: Requirement payload External service-->>-GitLab: Control response Note over External service,GitLab: Response includes SHA at HEAD

After the payload is received, the external service can run any required processes. The external service can then post its response back to the merge request by using the REST API.

External controls can have one of three statuses.

Status Description
pending Default status. No response received from the external service.
passed Response received from the external service and the external control was approved by the external service.
failed Response received from the external service and the external control was denied by the external service.

If something changes outside of GitLab, you can set the status of an external control by using the API. You don’t need to wait for a payload to be sent first.

Add requirements

To add a requirement when creating or editing a framework:

  1. On the left sidebar, select Search or go to and find your group.
  2. Select Secure > Compliance center.
  3. On the page, select the Frameworks tab.
  4. Select New framework or edit an existing one.
  5. In the Requirements section, select New requirement.
  6. In the dialog add Name and Description.
  7. Select Add a GitLab control to add more controls.
  8. In the control dropdown list search and select a control.
  9. Select Save changes to the framework to save the requirement.

Edit requirements

To edit a requirement when creating or editing a framework:

  1. On the left sidebar, select Search or go to and find your group.
  2. Select Secure > Compliance center.
  3. On the page, select the Frameworks tab.
  4. Select New framework or edit an existing one.
  5. In the Requirements section, select Action > Edit.
  6. In the dialog edit Name and Description.
  7. Select Add a GitLab control to add more controls.
  8. In the control dropdown list search and select a control.
  9. Select {{< icon name=”remove” >}} to remove a control.
  10. Select Save changes to the framework to save the requirement.