Compliance frameworks

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

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:
- The Owner role for the top-level group.
- Be assigned a custom role with the admin_compliance_framework custom permission.
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 by using either a compliance frameworks report or a compliance projects report.

For more information on using a compliance frameworks report, see:

For more information on using a compliance projects report, see:

Create a new compliance framework.
Edit a compliance framework.
Delete a compliance framework. 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

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:

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

Default compliance frameworks

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:

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

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

On the left sidebar, select Search or go to and find your group.
Select Secure > Compliance center.
On the page, select the Frameworks tab.
Hover over a compliance framework, select the Edit Framework tab.
Select Set as default.
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

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:

On the left sidebar, select Search or go to and find your group.
Select Secure > Compliance center.
On the page, select the Frameworks tab.
Locate the compliance framework you wish to export.
Select the vertical ellipsis ( ).
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. The JSON file must not have the same name as an existing compliance framework.

To import a compliance framework by using a JSON template:

On the left sidebar, select Search or go to and find your group.
Select Secure > Compliance center.
On the page, select the Frameworks tab.
Select New framework.
Select Import framework.
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

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

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.

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.

You can use GitLab compliance controls or external controls for 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.

Combine GitLab compliance controls to help you meet compliance standards.

Control name	Control ID	Description
API security running	`scanner_api_security_running`	Ensures that API security scanning is configured and running in the project’s default branch pipeline.
At least one approval	`minimum_approvals_required_1`	Ensures that merge requests require at least one approvals before merging.
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 is forbidden	`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 owner approval required	`code_owner_approval_required`	Ensures that code owners file is configured.
Code quality running	`scanner_code_quality_running`	Ensures that code quality scanning is configured and running in the project’s default branch pipeline.
Committers approved merge request is forbidden	`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’s default branch pipeline.
DAST running	`scanner_dast_running`	Ensures that Dynamic Application Security Testing (DAST) is configured and running in the project’s default branch pipeline.
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’s default branch pipeline.
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.
Forks exist for the project	`has_forks`	Ensures that the project has been forked
Fuzz testing running	`scanner_fuzz_testing_running`	Ensures that fuzz testing is configured and running in the project’s default branch pipeline.
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’s default branch pipeline.
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’s default branch pipeline.
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.
More members than admins	`more_members_than_admins`	Ensures fewer administrators are assigned to the project than total members.
Package Hunter no findings untriaged	`package_hunter_no_findings_untriaged`	Ensures that all Package Hunter findings are triaged.
Project not archived	`project_archived`	Checks whether the project is archived. Typically `false` is compliant.
Project not 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 repository exists	`project_repo_exists`	Ensures that a Git repository exists for the project.
Project visibility not public	`project_visibility_not_public`	Ensures that projects are not set to public visibility.
Protected branches exist	`protected_branches_set`	Ensures that project contains protected branches.
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 organization 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.
Requires signed commits	`require_signed_commits`	Ensures that signed commits are required.
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’s default branch pipeline.
Secret detection running	`scanner_secret_detection_running`	Ensures that secret detection scanning is configured and running in the project’s default branch pipeline.
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.
User-defined CI/CD variables restricted to maintainers	`project_user_defined_variables_restricted_to_maintainers`	Ensures that only users with the maintainer role or higher can pass user-defined variables when triggering pipelines.
Vulnerabilities SLO days over threshold	`vulnerabilities_slo_days_over_threshold`	Ensures that vulnerabilities are addressed inside SLO thresholds (180 days).

External controls

History

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:

On the left sidebar, select Search or go to and find your group.
Select Secure > Compliance center.
On the page, select the Frameworks tab.
Select New framework or edit an existing one.
In the Requirements section, select New requirement.
Select Add an external control.
In the fields edit External Control Name, External URL and HMAC shared secret.
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.
`pass`	Response received from the external service and the external control was approved by the external service.
`fail`	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.