• Restrictions
• Pipeline requirements
• Merge request with multiple pipelines
• Merge request approval policy editor
• Merge request approval policies schema
• Merge request approval policy schema
• scan_finding rule type
• license_finding rule type
• any_merge_request rule type
• require_approval action type
• send_bot_message action type
  • Example bot messages
• approval_settings
• fallback_behavior
• Security policy scopes
  • Policy scope schema
  • policy_scope scope type
  • Example policy.yml with security policy scopes
• Example security merge request approval policies project
• Example for Merge Request Approval Policy editor
• Understanding merge request approval policy approvals
  • Scope of merge request approval policy comparison
  • Accepting risk and ignoring vulnerabilities in future merge requests
  • Multiple approvals
  • Managing scan findings used to evaluate approval requirements
  • Filter out policy violations with the attributes “Fix Available” or “False Positive”
• Troubleshooting
  • Merge request rules widget shows a merge request approval policy is invalid or duplicated
  • Newly detected CVEs
  • Policies still have effect after policy.yml was manually invalidated
  • Support request for debugging of merge request approval policy
    • GitLab.com
    • GitLab self-managed

Merge request approval policies

Use merge request approval policies to enforce project-level settings and approval rules based on scan results. For example, one type of scan result policy is a security approval policy that allows approval to be required based on the findings of one or more security scan jobs. Merge request approval policies are evaluated after a CI scanning job is fully executed and both vulnerability and license type policies are evaluated based on the job artifact reports that are published in the completed pipeline.

The following video gives you an overview of GitLab merge request approval policies (previously scan result policies):

Restrictions

• You can enforce merge request approval policies only on protected target branches.
• You can assign a maximum of five rules to each policy.
• You can assign a maximum of five merge request approval policies to each security policy project.
• Policies created for a group or subgroup can take some time to apply to all the merge requests in the group.
• Merge request approval policies do not check the integrity or authenticity of the scan results generated in the artifact reports.
• A merge request approval policy is evaluated according to its rules. By default, if the rules are invalid, or can’t be evaluated, approval is required. You can change this behavior with the fallback_behavior field.

Pipeline requirements

A merge request approval policy is enforced according to the outcome of the pipeline. Consider the following when implementing a merge request approval policy:

• A merge request approval policy evaluates completed pipeline jobs, ignoring manual jobs. When the manual jobs are run, the policy re-evaluates the merge request’s jobs.
• All configured scanners must be present in the merge request’s latest pipeline. If not, approvals are required even if some vulnerability criteria have not been met.
• The pipeline must produce artifacts for all enabled scanners, for both the source and target branches. If not, there’s no basis for comparison and so the policy can’t be evaluated. You should use a scan execution policy to enforce this requirement.
• Policy evaluation depends on a successful and completed merge base pipeline. If the merge base pipeline is skipped, merge requests with the merge base pipeline are blocked.
• Security scanners specified in a policy must be configured and enabled in the projects on which the policy is enforced. If not, the merge request approval policy cannot be evaluated and the corresponding approvals are required.

Merge request with multiple pipelines

A project can have multiple pipeline types configured. A single commit can initiate multiple pipelines, each of which may contain a security scan.

• In GitLab 16.3 and later, the results of all completed pipelines for the latest commit in the merge request’s source and target branch are evaluated and used to enforce the merge request approval policy. On-demand DAST pipelines are not considered.
• In GitLab 16.2 and earlier, only the results of the latest completed pipeline were evaluated when enforcing merge request approval policies.

If a project uses merge request pipelines, you must use the latest security templates so that the security scanning jobs are present in the pipeline. For more information see Use security scanning tools with merge request pipelines.

Merge request approval policy editor

Once your policy is complete, save it by selecting Configure with a merge request at the bottom of the editor. This redirects you to the merge request on the project’s configured security policy project. If a security policy project doesn’t link to your project, GitLab creates such a project for you. Existing policies can also be removed from the editor interface by selecting Delete policy at the bottom of the editor.

Most policy changes take effect as soon as the merge request is merged. Any changes that do not go through a merge request and are committed directly to the default branch may require up to 10 minutes before the policy changes take effect.

The policy editor supports YAML mode and rule mode.

Merge request approval policies schema

The YAML file with merge request approval policies consists of an array of objects matching the merge request approval policy schema nested under the approval_policy key. You can configure a maximum of five policies under the approval_policy key.

When you save a new policy, GitLab validates its contents against this JSON schema. If you’re not familiar with how to read JSON schemas, the following sections and tables provide an alternative.

Merge request approval policy schema

scan_finding rule type

This rule enforces the defined actions based on security scan findings.

license_finding rule type

This rule enforces the defined actions based on license findings.

any_merge_request rule type

This rule enforces the defined actions for any merge request based on the commits signature.

require_approval action type

This action sets an approval rule to be required when conditions are met for at least one rule in the defined policy.

send_bot_message action type

This action enables configuration of the bot message in merge requests when policy violations are detected. If the action is not specified, the bot message is enabled by default. If there are multiple policies defined, the bot message is sent as long as at least one of those policies has the send_bot_message action is enabled.

Example bot messages

approval_settings

The settings set in the policy overwrite settings in the project.

fallback_behavior

Security policy scopes

Security policy enforcement depends first on establishing a link between the group, subgroup, or project on which you want to enforce policies, and the security policy project that contains the policies. For example, if you are linking policies to a group, a group owner must create the link to the security policy project. Then, all policies in the security policy project are inherited by all projects in the group.

You can refine a security policy’s scope to:

• Include only projects containing a compliance framework label.
• Include or exclude selected projects from enforcement.
• Include selected groups. Optionally use this with the projects object to exclude selected projects.

Policy scope schema

policy_scope scope type

Example policy.yml with security policy scopes

---
approval_policy:
- name: critical vulnerability CS approvals
  description: critical severity level only for container scanning
  enabled: true
  rules:
  - type: scan_finding
    branches:
    - main
    scanners:
    - container_scanning
    vulnerabilities_allowed: 1
    severity_levels:
    - critical
    vulnerability_states: []
  actions:
  - type: require_approval
    approvals_required: 1
    user_approvers:
    - adalberto.dare
  policy_scope:
    compliance_frameworks:
      - id: 2
      - id: 11
    projects:
      including:
        - id: 24
        - id: 27

Example security merge request approval policies project

You can use this example in a .gitlab/security-policies/policy.yml file stored in a security policy project:

---
approval_policy:
- name: critical vulnerability CS approvals
  description: critical severity level only for container scanning
  enabled: true
  rules:
  - type: scan_finding
    branches:
    - main
    scanners:
    - container_scanning
    vulnerabilities_allowed: 0
    severity_levels:
    - critical
    vulnerability_states: []
    vulnerability_attributes:
      false_positive: true
      fix_available: true
  actions:
  - type: require_approval
    approvals_required: 1
    user_approvers:
    - adalberto.dare
- name: secondary CS approvals
  description: secondary only for container scanning
  enabled: true
  rules:
  - type: scan_finding
    branches:
    - main
    scanners:
    - container_scanning
    vulnerabilities_allowed: 1
    severity_levels:
    - low
    - unknown
    vulnerability_states:
    - detected
    vulnerability_age:
      operator: greater_than
      value: 30
      interval: day
  actions:
  - type: require_approval
    approvals_required: 1
    role_approvers:
    - owner

In this example:

• Every MR that contains new critical vulnerabilities identified by container scanning requires one approval from alberto.dare.
• Every MR that contains more than one preexisting low or unknown vulnerability older than 30 days identified by container scanning requires one approval from a project member with the Owner role.

Example for Merge Request Approval Policy editor

You can use this example in the YAML mode of the Merge Request Approval Policy editor. It corresponds to a single object from the previous example:

type: approval_policy
name: critical vulnerability CS approvals
description: critical severity level only for container scanning
enabled: true
rules:
- type: scan_finding
  branches:
  - main
  scanners:
  - container_scanning
  vulnerabilities_allowed: 1
  severity_levels:
  - critical
  vulnerability_states: []
actions:
- type: require_approval
  approvals_required: 1
  user_approvers:
  - adalberto.dare

Understanding merge request approval policy approvals

Scope of merge request approval policy comparison

• To determine when approval is required on a merge request, we compare completed pipelines for each supported pipeline source for the source and target branch (for example, feature/main). This ensures the most comprehensive evaluation of scan results.
• For the source branch, the comparison pipelines are all completed pipelines for each supported pipeline source for the latest commit in the source branch.
• If the merge request approval policy looks only for the newly detected states (new_needs_triage & new_dismissed), the comparison is performed against all the supported pipeline sources in the common ancestor between the source and the target branch. An exception is when using Merged Results pipelines, in which case the comparison is done against the tip of the MR’s target branch.
• If the merge request approval policy looks for pre-existing states (detected, confirmed, resolved, dismissed), the comparison is always done against the tip of the default branch (for example, main).
• If the merge request approval policy looks for a combination of new and pre-existing vulnerabilty states, the comparison is done against the common ancestor of the source and target branches.
• Merge request approval policies considers all supported pipeline sources (based on the CI_PIPELINE_SOURCE variable) when comparing results from both the source and target branches when determining if a merge request requires approval. Pipelines with source webide are not supported.
• In GitLab 16.11 and later, the child pipelines of each of the selected pipelines are also considered for comparison. This is available with a flag named approval_policy_parent_child_pipeline.

Accepting risk and ignoring vulnerabilities in future merge requests

For merge request approval policies that are scoped to newly detected findings(new_needs_triage or new_dismissed statuses), it’s important to understand the implications of this vulnerability state. A finding is considered newly detected if it exists on the merge request’s branch but not on the default branch. When a merge request whose branch contains newly detected findings is approved and merged, approvers are “accepting the risk” of those vulnerabilities. If one or more of the same vulnerabilities were detected after this time, their status would be detected and so not be out of scope of a policy aimed at new_needs_triage or new_dismissed findings. For example:

• A merge request approval policy is created to block critical SAST findings. If a SAST finding for CVE-1234 is approved, future merge requests with the same violation will not require approval in the project.

When using license approval policies, the combination of project, component (dependency), and license are considered in the evaluation. If a license is approved as an exception, future merge requests don’t require approval for the same combination of project, component (dependency), and license. The component’s version is not be considered in this case. If a previously approved package is updated to a new version, approvers will not need to re-approve. For example:

• A license approval policy is created to block merge requests with newly detected licenses matching AGPL-1.0. A change is made in project demo for component osframework that violates the policy. If approved and merged, future merge requests to osframework in project demo with the license AGPL-1.0 don’t require approval.

Multiple approvals

There are several situations where the merge request approval policy requires an additional approval step. For example:

• The number of security jobs is reduced in the working branch and no longer matches the number of security jobs in the target branch. Users can’t skip the Scanning Result Policies by removing scanning jobs from the CI/CD configuration. Only the security scans that are configured in the merge request approval policy rules are checked for removal.

  For example, consider a situation where the default branch pipeline has four security scans: sast, secret_detection, container_scanning, and dependency_scanning. A merge request approval policy enforces two scanners: container_scanning and dependency_scanning. If an MR removes a scan that is configured in merge request approval policy, container_scanning for example, an additional approval is required.

• Someone stops a pipeline security job, and users can’t skip the security scan.
• A job in a merge request fails and is configured with allow_failure: false. As a result, the pipeline is in a blocked state.
• A pipeline has a manual job that must run successfully for the entire pipeline to pass.

Managing scan findings used to evaluate approval requirements

Merge request approval policies evaluate the artifact reports generated by scanners in your pipelines after the pipeline has completed. Merge request approval policies focus on evaluating the results and determining approvals based on the scan result findings to identify potential risks, block merge requests, and require approval.

Merge request approval policies do not extend beyond that scope to reach into artifact files or scanners. Instead, we trust the results from artifact reports. This gives teams flexibility in managing their scan execution and supply chain, and customizing scan results generated in artifact reports (for example, to filter out false positives) if needed.

Lock file tampering, for example, is outside of the scope of security policy management, but may be mitigated through use of Code owners or external status checks. For more information, see issue 433029.

Filter out policy violations with the attributes “Fix Available” or “False Positive”

To avoid unnecessary approval requirements, these additional filters help ensure you only block MRs on the most actionable findings.

By setting fix_available to false in YAML, or is not and Fix Available in the policy editor, the finding is not considered a policy violation when the finding has a solution or remediation available. Solutions appear at the bottom of the vulnerability object under the heading Solution. Remediations appear as a Resolve with Merge Request button within the vulnerability object.

The Resolve with Merge Request button only appears when one of the following criteria is met:

1. A SAST vulnerability is found in a project that is on the Ultimate Tier with GitLab Duo Enterprise.
2. A container scanning vulnerability is found in a project that is on the Ultimate Tier in a job where GIT_STRATEGY: fetch has been set. Additionally, the vulnerability must have a package containing a fix that is available for the repositories enabled for the container image.
3. A dependency scanning vulnerability is found in a Node.js project that is managed by yarn and a fix is available. Additionally, the project must be on the Ultimate Tier and FIPS mode must be disabled for the instance.

Fix Available only applies to dependency scanning and container scanning.

By using the False Positive attribute, similarly, you can ignore findings detected by a policy by setting false_positive to false (or set attribute to Is not and False Positive in the policy editor).

The False Positive attribute only applies to findings detected by our Vulnerability Extraction Tool for SAST results.

Troubleshooting

Merge request rules widget shows a merge request approval policy is invalid or duplicated

On GitLab self-managed from 15.0 to 16.4, the most likely cause is that the project was exported from a group and imported into another, and had merge request approval policy rules. These rules are stored in a separate project to the one that was exported. As a result, the project contains policy rules that reference entities that don’t exist in the imported project’s group. The result is policy rules that are invalid, duplicated, or both.

To remove all invalid merge request approval policy rules from a GitLab instance, an administrator can run the following script in the Rails console.

Project.joins(:approval_rules).where(approval_rules: { report_type: %i[scan_finding license_scanning] }).where.not(approval_rules: { security_orchestration_policy_configuration_id: nil }).find_in_batches.flat_map do |batch|
  batch.map do |project|
    # Get projects and their configuration_ids for applicable project rules
    [project, project.approval_rules.where(report_type: %i[scan_finding license_scanning]).pluck(:security_orchestration_policy_configuration_id).uniq]
  end.uniq.map do |project, configuration_ids| # We take only unique combinations of project + configuration_ids
    # If we find more configurations than what is available for the project, we take records with the extra configurations
    [project, configuration_ids - project.all_security_orchestration_policy_configurations.pluck(:id)]
  end.select { |_project, configuration_ids| configuration_ids.any? }
end.each do |project, configuration_ids|
  # For each found pair project + ghost configuration, we remove these rules for a given project
  Security::OrchestrationPolicyConfiguration.where(id: configuration_ids).each do |configuration|
    configuration.delete_scan_finding_rules_for_project(project.id)
  end
  # Ensure we sync any potential rules from new group's policy
  Security::ScanResultPolicies::SyncProjectWorker.perform_async(project.id)
end

Newly detected CVEs

When using new_needs_triage and new_dismissed, some findings may require approval when they are not introduced by the merge request (such as a new CVE on a related dependency). These findings will not be present within the MR widget, but will be highlighted in the policy bot comment and pipeline report.

Policies still have effect after policy.yml was manually invalidated

In GitLab 17.2 and earlier, you may find that policies defined in a policy.yml file are enforced, even though the file was manually edited and no longer validates against the policy schema. This issue occurs because of a bug in the policy synchronization logic.

Potential symptoms include:

• approval_settings still block the removal of branch protections, block force-pushes or otherwise affect open merge requests.
• any_merge_request policies still apply to open merge requests.

To resolve this you can:

• Manually edit the policy.yml file that defines the policy so that it becomes valid again.
• Unassign and re-assign the security policy projects where the policy.yml file is stored.

Support request for debugging of merge request approval policy

GitLab.com users may submit a support ticket titled “Merge request approval policy debugging”. Provide the following details:

• Group path, project path and optionally merge request ID
• Severity
• Current behavior
• Expected behavior

GitLab.com

Support teams will investigate logs (pubsub-sidekiq-inf-gprd*) to identify the failure reason. Below is an example response snippet from logs. You can use this query to find logs related to approvals: json.event.keyword: "update_approvals" and json.project_path: "group-path/project-path". Optionally, you can further filter by the merge request identifier using json.merge_request_iid:

"json": {
  "project_path": "group-path/project-path",
  "merge_request_iid": 2,
  "missing_scans": [
    "api_fuzzing"
  ],
  "reason": "Scanner removed by MR",
  "event": "update_approvals",
}

GitLab self-managed

Search for keywords such as the project-path, api_fuzzing, and merge_request. Example: grep group-path/project-path, and grep merge_request. If you know the correlation ID you can search by correlation ID. For example, if the value of correlation_id is 01HWN2NFABCEDFG, search for 01HWN2NFABCEDFG. Search in the following files:

• /gitlab/gitlab-rails/production_json.log
• /gitlab/sidekiq/current

Common failure reasons:

• Scanner removed by MR: Merge request approval policy expects that the scanners defined in the policy are present and that they successfully produce an artifact for comparison.