A shared security policy can give teams dependable checks without asking every project to maintain them. But a rule that looks straightforward in the policy editor can behave very differently in a large repository, a release branch, or a pipeline that can't reach the scanner's registry. If it immediately blocks delivery, developers inherit those problems before the people introducing the rule understand them.
Start with the teams who'll use the policy. Get the scans working, look at the decisions their results would require, and give developers a way to resolve findings or ask for an exception. Then introduce enforcement and expand its reach. That progression helps you improve coverage without turning every scanner problem into an urgent approval request.
Start with the decision you want to improve
“Run SAST on our application changes” and “ask Security to review new High or Critical findings before merge” sound related, but they need different arrangements. The first needs reliable jobs and reports. The second needs a rule for when another person should decide, enough qualified reviewers, and a response that fits the team's delivery schedule.
GitLab separates these responsibilities into policy types.1 Choose the one that addresses the gap you have:
- Scan execution policies run supported GitLab scanners in pipelines or on a schedule. They're a good starting point when the standard scanners and their configuration options meet your needs.
- Pipeline execution policies apply centrally maintained CI/CD jobs. They fit custom checks, third-party scanners, and workflows that need more control over how jobs run.
- Merge request approval policies decide when a change needs additional approval, using scan results or other conditions. They don't arrange the scans for you.
You might need an execution policy and an approval policy together, but introduce them as separate changes. If a scanner stops working, the platform team needs to restore it. If the scanner finds a genuine vulnerability, the application team needs to understand and address it. If a release needs to proceed before a fix is ready, someone authorized to accept that risk needs to decide. Naming those responsibilities early gives developers somewhere to turn besides retrying the pipeline.
Be clear about whether the new rule addresses findings introduced by a change or vulnerabilities already present. Stopping new problems and reducing an existing backlog are different kinds of work. A rule aimed at existing findings may also require approval on an MR that fixes one, because it evaluates the findings already recorded rather than treating the proposed fix as complete. Choose that behavior deliberately, not as a side effect of selecting every finding state.
If your immediate problem is an unmanageable vulnerability backlog, begin with triage and follow-through. Vulnerability management policies can automate established handling rules later; they aren't a substitute for deciding how findings should be handled.
Choose projects that reflect the work ahead
Start with projects whose maintainers can work with you through the change. Include the differences you're likely to encounter next: languages, repository size, branch models, runner environments, and network access. A familiar service helps you see the basic behavior; a larger repository or a restricted runner network helps you understand what a wider rollout will demand. Choose a group you can support closely without mistaking one easy case for the rest of the organization.
Walk through a recent merge request with its author or maintainer. Find where the pipeline starts, where scans run, how findings reach the reviewer, and what happens if the scanner fails. Notice any work that happens outside the default branch: release branches and parent-child pipelines can change which reports are available. Record the current pipeline duration and queue time so you can distinguish new delays from existing ones.
Agree with Security, application maintainers, and the platform and runner owners on what would make the first rollout successful. For example, developers should be able to understand a finding, get a decision when they need one, and keep ordinary changes moving. A new rule that catches the intended problem but adds days of waiting for an unavailable reviewer still needs work.
Make the reports dependable before relying on them
If you're still choosing scanners or deciding where they should run, establish security scan coverage helps you work through those choices before introducing policy.
Configure the required scanners and let them finish on the default branch before introducing a finding-based approval policy. Then open a representative merge request with the same scanner configuration. For work targeting a release branch, check that branch too. You're establishing that GitLab has reports to compare, not just that a job with a familiar name appeared.
A rule looking for new findings needs results from both sides of the change. A missing target report can make an old vulnerability appear to be new; an older feature branch can lack the scanner configuration that's now on the default branch. GitLab also needs the relevant merge-base pipeline to complete successfully. Its pipeline requirements explain how these comparisons affect approval. Restore missing reports before interpreting the approval request as a newly introduced vulnerability.
Try a clean change and a temporary change that the scanner should detect, without merging the latter. Read the actual report and the message a developer receives. Can they find the affected code or dependency and understand why the rule applies? If the report isn't understandable at this stage, making it mandatory won't improve it.
Watch the work needed to produce the report as well. A successful upload doesn't tell you whether every preparation job completed or whether the scanner examined the intended code, dependencies, or image. Trace failures in resolution or build jobs rather than relying only on the final scanning job's status.
Keep an eye on runner queues, scan duration, resource use, and access to analyzer images or advisory data. Estimate the additional concurrent jobs at busy times before adding more projects. When scans are slow, investigate the cause with the runner owner; increasing the approval burden won't solve a capacity problem.
Protect policy changes and limit their first reach
Use a security policy project to keep .gitlab/security-policies/policy.yml outside the application repositories it governs. Protect its default branch and review changes through merge requests. A separate repository doesn't provide independence if application maintainers inherit permission to change it without review. Protected changes with independent review explains how to arrange that review.
Placement affects inherited access. For a rollout across one GitLab.com namespace, a dedicated policy subgroup gives teams a central place to manage the rules, but still inherits permissions from its parents. GitLab's Self-Managed and Dedicated guidance also describes using a standalone group to reduce that inheritance. Choose the arrangement around who should manage policy, then examine the actual access rather than assuming a separate repository is independent. By default, Owners and Maintainers can modify policies; linking a policy project requires an Owner or a custom role with manage_security_policy_link. Review who can change both the policies and their links. The policy project guidance covers placement and linking, including links across top-level groups.
Linking at a group applies policies down its hierarchy, subject to each policy's scope. New projects can inherit them too. For the first rollout, list the projects to include or choose a small group, and inspect the policies already inherited by those projects. A local warning policy doesn't cancel an enforced policy inherited from a parent group. Make changes with the owner of the policy that's actually responsible for the requirement.
Before enabling a policy, compare its scope with the projects you meant to include. An empty including list isn't an empty rollout: GitLab treats it as no restriction. Use enabled: false when you mean to disable the policy. Keeping the initial scope simple makes both expansion and recovery easier to reason about.
Move working scans into shared policy
Apply the execution policy to the initial projects and compare its jobs with the configuration you already understand. Keep the previous configuration available for recovery, but remove unnecessary duplicate jobs once the centrally managed scans produce the intended reports. Duplicate scans can add queue time and present developers with different results from different settings.
For scan execution policies, use the scanner's recommended stable or versioned template. The latest option is experimental, not simply a newer recommended default. When the projects use merge request pipelines, set AST_ENABLE_MR_PIPELINES to "true" in the policy for each enforced scan. Also check the project's workflow:rules: pipeline-based scan execution policies depend on those rules allowing the pipeline to be created. A scheduled scan can supplement coverage, but it doesn't replace feedback on the change being reviewed.
For pipeline execution policies, choose the strategy according to what you want to preserve. inject_policy adds jobs while retaining the application pipeline; override_project_ci replaces its configuration unless you deliberately include it. Policy and project workflow rules are evaluated separately with inject_policy, so suppressing the project jobs doesn't necessarily suppress the policy jobs. Check merge request and branch pipelines rather than assuming a rule that worked locally behaves the same when moved into a policy.
Policy CI/CD variables also need attention. Pipeline execution policies run in isolation by default, so a project or group variable may not reach the injected job. Define the scanner settings in the policy configuration or deliberately allow the required overrides. Use the CI/CD variable guidance when making that choice. Secrets need a secure retrieval mechanism, not values committed to the policy repository.
Run a pipeline as an ordinary application contributor, not only as the policy owner. Pipeline execution policies need access to the referenced CI/CD configuration. Arrange the documented read access or automatic configuration access without granting policy-editing rights. Check stage ordering and job-name conflicts as well; an error in a shared include can otherwise prevent every affected project from starting a pipeline.
If a project still uses deprecated compliance pipelines, migrate that configuration before introducing a pipeline execution policy. Combining them can produce missing or duplicated jobs because they apply configuration differently. Treat this as a migration of the required checks, including confirmation that each check still runs, rather than simply attaching another policy.
Learn from warnings before requiring approval
Once the reports are reliable, introduce the new merge request approval policy with enforcement_type: warn. Scope it to the intended protected target branches. GitLab shows violations, but someone still has to approve them or choose to bypass them with a reason; warn mode doesn't silently make the merge request ready to merge. Other approval and pipeline requirements continue to apply.
Keep existing mandatory protections in place. In warn mode, this policy's approval_settings overrides aren't enforced. Moving an existing required control into warn mode would relax it, not merely give you a preview of a new rule.
Review the warnings with the developers receiving them. A bypass might describe a genuine exception, a scanner problem, or a rule that doesn't fit the application. Those need different responses. Several teams reporting the same confusing message may need clearer instructions; repeated accepted exceptions may mean the criteria are too broad. A real finding that developers fix before merge is a reason to keep the rule, even if it briefly interrupts their work.
Keep the reasons connected to the merge requests. Audit events record that a warn-mode bypass occurred after merge, but they don't contain its explanation. Reviewing only the count would miss the information you need to improve the rule.
Work through failures and exceptions with the team
Use the first projects to rehearse the awkward cases as well as a clean merge. You want to learn whether people can recover, not just whether a warning appears.
When a report is missing
Find out whether the scanner never ran, failed to produce an artifact, or produced a report GitLab couldn't use. Follow the pipeline and job logs on the relevant branches. If the target report is absent, restore scanning there and rerun the source pipeline so the comparison can be made again.
By default, an approval policy that can't evaluate a rule requires approval. Setting fail: open under fallback_behavior lets the change proceed without that approval when GitLab can't evaluate the rule. That's different from warn mode, which lets someone bypass a reported violation with a reason. Choose the fallback behavior with the security owner, including how missing coverage will be noticed and restored. A recurring broken scan needs a fix rather than a standing exemption.
When the pipeline itself is blocked
Identify the requirement preventing the merge. Bypassing a warning doesn't repair a failed job or satisfy Pipelines must succeed. If the pipeline is waiting for a manual job, establish whether that job is intentionally required before changing the approval policy. Ask the platform owner to address job execution problems and the security reviewer to address findings; sending both to the approval queue obscures the cause.
Approval policies' failed-scan handling isn't a general check that every pipeline job succeeded. Pay attention to the scanners selected by the rule and any jobs they depend on. Keep normal pipeline protections alongside security approval rules, and use the approval troubleshooting guidance when the displayed requirement is unexpected.
When delivery needs an exception
Work through a realistic request with the application team and the person who can accept the risk. Record the affected finding and change, why proceeding is reasonable, any temporary protection, who approved it, and when the decision needs another look. Link the follow-up fix so the exception doesn't become the last action anyone takes.
A bypass reason during a warning trial helps you learn; it doesn't by itself constitute your organization's risk acceptance. Before enforcement, agree which decisions a designated approver can make and how urgent requests reach someone when the usual reviewer is away. Confirm that eligible reviewers can meet the required approval count, including the restrictions on authors and committers approving their own work.
Keep exceptions as narrow as the situation permits. Exempting a branch, identity, or automation account can affect more than the merge request that prompted the change. If you use a policy bypass setting, review that continuing access separately from the one-time release decision. Make sure the team knows how a temporary exception ends, including any manual removal the chosen mechanism requires.
Introduce enforcement, then expand
Move to enforcement_type: enforce when you can explain the warnings, scans are dependable, and developers can get timely decisions. Fix false positives and coverage gaps first. Keep the scan configuration and project scope stable during that change so you can see the effect of requiring approval on its own.
Follow actual work through the new requirement. Check that an ordinary change moves normally, an intended finding reaches the right reviewer, and an exception leaves an understandable decision and follow-up. Retain those merge requests as examples for the next teams. They also give you a way to revisit behavior after a scanner or policy update.
Expand to projects with similar needs before taking on another pipeline pattern. As you broaden group scope, consider new projects and projects moved into that group: they may inherit requirements before their first usable reports exist. Include scanner setup and an initial default-branch run in project onboarding, and make the policy contact easy to find.
Review coverage and delivery together. Look at missing reports, runner delay, time waiting for a decision, and what happens to genuine findings. Fewer blocked merge requests can mean developers are fixing problems earlier; it can also mean scans stopped running. Discuss both the reports and developers' experience before deciding the rollout is working.
Keep recovery focused on the problem
Prepare a reviewed way to restore the previous policy configuration before broadening its scope. Name who can make that change and who can review it during an interruption. Confirm the corrected behavior in an affected project, and check that a project outside the changed scope kept its protections. Merging the policy MR isn't enough to know every project has synchronized.
If the new approval criteria are the problem, narrow or return that policy to warn while preserving working scans and existing protections. If the execution policy is breaking pipelines, restore the previous scanner configuration or narrow the affected execution policy instead. Changing approval mode won't fix pipeline creation, and disabling the scanner to clear an approval problem removes the information reviewers need.
Avoid unlinking the entire security policy project as the first response. That can remove unrelated policies without addressing policies inherited elsewhere. Change the specific rule or scope responsible for the interruption, and confirm the resulting jobs and approval requirements. Scan execution policy updates apply to future runs, so start a new pipeline to inspect the recovered behavior rather than expecting an in-progress pipeline to change.
Once work is moving again, use the interrupted merge requests to improve the rollout: add the missed project pattern, correct the rule, or improve scanner operation and response coverage. Recovery should leave the team better able to handle the next change, not dependent on remembering an undocumented exemption.
Further Reading
Notes
-
Security policies are available in Ultimate on GitLab.com, Self-Managed, and Dedicated. They enforce centrally managed checks and approval rules. The practices of reliable scanning, independent review, and staged rollout remain valuable without them; ordinary shared CI/CD includes don't prevent a project from removing a check. ↩
- Configure security scanners explains template choices and merge request scanning.
- Set up a security policy project covers storage, access, and linking policies to projects and groups.
- Choose policy scope explains project inclusion, exclusions, and how combined conditions affect coverage.
- Configure scan execution policies covers scanner settings, schedules, duplicate scans, and pipeline creation.
- Configure pipeline execution policies explains injection strategies, configuration access, variables, and compliance-pipeline migration.
- Set approval policy behavior covers report requirements, warning bypasses, fallback choices, and troubleshooting.