skip to content

In GitLab Ultimate, how do scan execution policies and merge request approval policies work together so that a new critical finding needs a security approver?

level: seniorimportance: should knowfreq 27%

answer

  1. one makes scans run, one judges results
  2. scan_finding rule, require_approval action
  3. protected target branches only
  4. fails closed when reports are missing

basics

~20 s

A scan execution policy forces scanners into every in-scope pipeline, overriding project configuration. A merge request approval policy reads the resulting reports and requires named approvers when a new critical appears. One guarantees the evidence; the other gates on it.

solid answer

~50 s

Both are Ultimate policy types kept in `.gitlab/security-policies/policy.yml` in a security policy project linked to the group. A **scan execution policy** has `pipeline` or `schedule` rules and `scan` actions (`sast`, `secret_detection`, `dependency_scanning`, `container_scanning` and more). GitLab injects those jobs into every in-scope pipeline, and project YAML cannot override them. It makes scans run but judges nothing, since a scan job passes whatever it finds. A **merge request approval policy** (`approval_policy`) pairs a `scan_finding` rule (scanners, `severity_levels: [critical]`, `vulnerabilities_allowed: 0`, `vulnerability_states: []` for newly detected) with a `require_approval` action naming `group_approvers`. It applies only to protected target branches and fails closed: if a required scanner produced no report, approval is required, and since 19.4 a failed or canceled scan job triggers that too. That is why the two are paired. Use `policy_scope` and `enforcement_type: warn` to avoid blocking every project at once.

code

yaml · 15 lines
yaml
approval_policy:
- name: New critical findings need AppSec
  enabled: true
  rules:
  - type: scan_finding
    branch_type: protected
    scanners: [sast, secret_detection, dependency_scanning, container_scanning]
    vulnerabilities_allowed: 0
    severity_levels: [critical]
    vulnerability_states: []
  actions:
  - type: require_approval
    approvals_required: 1
    group_approvers:
    - acme/appsec

go deeper

for a junior

Know there are two policy types: one makes scans run and one requires approval when scans find something.

for a middle

Explain a scan_finding rule's fields and the require_approval action, and why policies apply only to protected target branches.

for a senior

Design the pairing: enforce scanners so approval policies do not fail closed, scope policies, start in warn mode, and anticipate risk acceptance and re-evaluation gaps.

for a principal

Own the governance trade-off: which findings justify a human gate, who may approve, and how much developer friction the organisation accepts for that assurance.

## Two policy types, two jobs GitLab Ultimate's security policies split enforcement into separate types. Two of them do the work in this scenario: | | Scan execution policy | Merge request approval policy | |---|---|---| | Purpose | Make security scans run | Require approval based on scan results | | YAML key | `scan_execution_policy` | `approval_policy` | | Rules | `pipeline` (branches, branch types, pipeline sources) or `schedule` | `scan_finding`, `license_finding` or `any_merge_request` | | Actions | `scan` (`sast`, `sast_iac`, `secret_detection`, `dependency_scanning`, `container_scanning`, `dast`) | `require_approval`, `send_bot_message` | | Effect on a merge | None directly | Adds required approvals when its rules match | The split matters because **findings do not fail the scan jobs** these policies inject. A scan execution policy guarantees the evidence exists; only a merge request approval policy turns evidence into a merge requirement. Another type, the pipeline execution policy, forces arbitrary CI/CD jobs and belongs with CI configuration rather than here. ## Where policies live - Policies are YAML in `.gitlab/security-policies/policy.yml` inside a **security policy project**. - A group Owner, or a custom role with the `manage_security_policy_link` permission, links that project to the group, and policies then apply to its subgroups and projects. - Edit policies through the policy editor or a merge request into the policy project; GitLab synchronizes policy changes when such a merge request is merged. - Each security policy project holds at most five scan execution policies and five merge request approval policies, each with up to five rules. ## How a scan execution policy injects scans - With a `pipeline` rule, GitLab adds the scan jobs to every pipeline on the matching branches. A project without a `.gitlab-ci.yml` gets one implicitly, so scanners that need no build still run. - Policy jobs take precedence over the project's own configuration, even when a job uses the same name. Their names get a numeric suffix, so `secret-detection` becomes `secret-detection-1`. - Jobs run in the `test` stage (DAST in a `dast` stage), and GitLab injects a `scan-policies` stage if `test` has been removed. - Projects that use merge request pipelines need `AST_ENABLE_MR_PIPELINES: "true"` among the policy's variables for each enforced scan. - A `schedule` rule runs scans on a cadence, independent of commits. ## How a merge request approval policy decides 1. The pipeline completes. Manual jobs are ignored until they run. 2. GitLab compares the source branch's security reports with the target side. For newly detected states, the baseline is the common ancestor of the two branches, or the target branch's tip with merged results pipelines. 3. A `scan_finding` rule matches when more than `vulnerabilities_allowed` findings of the listed `severity_levels` and `vulnerability_states` come from the listed `scanners`. An empty `vulnerability_states` covers the newly detected states, `new_needs_triage` and `new_dismissed`. 4. A match makes the `require_approval` action mandatory. With `group_approvers`, direct members of that group are eligible. 5. The policy applies **only to protected target branches**. 6. It **fails closed**. If a scanner the rule needs produced no report on either side, approval is required, which is the default `fallback_behavior` of `fail: closed`. In GitLab 19.4 a scanner job that ended `failed`, `canceled` or `canceling` without a report also requires approval, even when other scanners succeeded. 7. Removing a policy-listed scan job from the branch's pipeline also triggers an extra approval, so a developer cannot dodge the rule by deleting the scanner. Pair the approval policy with a scan execution policy, so the scanners it needs always run and the policy does not fail closed on every merge request. ## Not blocking every project in the group - **Scope** policies with `policy_scope`, including or excluding projects, groups or compliance frameworks. Beware that an empty collection, such as `projects: { including: [] }`, applies the policy to **all** projects, not to none; use `enabled: false` to switch a policy off. - **Start in warn mode.** With `enforcement_type: warn`, generally available since GitLab 18.9, violations produce bot comments and the merge request can bypass them with a stated reason, which is audited. Switch to `enforce` when the noise is understood. - **Scan default branches first.** Without a baseline on the target branch, the policy cannot compare and approvals pile up. - **Target branch types**, such as `protected` or `default`, rather than branch names that differ between projects. ## Traps in operation - Approving a newly detected finding accepts its risk. When the same vulnerability appears in a later merge request it is already `detected`, so a policy that only watches new states will not stop it again. - Dismissing a vulnerability does not re-evaluate open merge requests. Re-run the pipeline or push a commit. - Approval policies trust the report artifacts and do not verify that they are authentic.

  • Why does a new GitLab project in scope of a merge request approval policy have every merge request blocked before anyone has written code?
    The policy fails closed: the scanners its rule lists must have produced reports on both the source and the target side, and a brand-new project has no scanned default branch yet. Enforce the scanners with a scan execution policy, let a default-branch pipeline complete, then open merge requests.
  • In GitLab, a developer deletes the container scanning job from a merge request's pipeline. Does that escape a merge request approval policy that lists container_scanning?
    No. When a branch's pipeline runs fewer of the policy's listed security jobs than the target branch, GitLab requires an additional approval. If a scan execution policy enforces that scanner, the removal does not work at all, because policy jobs take precedence over project configuration.
  • In a GitLab merge request approval policy, how do you require two approvals from two different approver sets?
    Use two require_approval actions. Approvers listed in a single action are interchangeable, so two group_approvers with approvals_required: 2 can both be satisfied by members of the same group. Separate actions, up to five, each need their own approvals.

A scan execution policy is the building rule that every room gets a smoke detector; a merge request approval policy is the rule that an alarm, or a room whose detector is missing or broken, needs the fire officer's signature before anyone moves in.

  • A scan execution policy blocks the merge when its scan finds a critical vulnerability.
  • A merge request approval policy with no reports to read lets the merge through.
  • Merge request approval policies apply to every target branch, protected or not.
  • policy_scope with an empty including list applies the policy to no projects.
  • Project maintainers can override a scan execution policy's job by redefining it in .gitlab-ci.yml.

Assumes GitLab 19.4; blocking on failed or canceled scan jobs is enabled by default in 19.4, and warn mode (enforcement_type: warn) has been generally available since 18.9.