Security checks need to fit the team's normal delivery workflow. Start by enabling scanner coverage, then add agent-assisted review and triage where they help people act on the results. Keep the decision to accept a change with controls that its author can't alter.
| Standard example control | Implementation steps |
|---|---|
| Policy in the execution path | Enable scanner profiles, align application tests and scanners, then connect required checks to admission. Profile attachment alone doesn't enforce merge. |
| Protected checks | Separate policy administration, protect its branch, and inspect who can change scanner, profile and execution inputs. |
| Separation of duties | Review DAP proposals and configure independent approval. An agent's assessment isn't an approval. |
Enable SAST, SCA and secret detection
GitLab security configuration profiles enable scanners without adding templates to each project's .gitlab-ci.yml. This procedure uses the default profiles for static application security testing (SAST), dependency scanning, and secret detection. For software composition analysis (SCA), this walkthrough uses GitLab Dependency scanning to identify vulnerable application dependencies.
Use the representative application selected during preparation. If you're continuing in practice-application, add reviewed application source and dependency inputs first; a README-only project won't exercise SAST or dependency scanning.
Profiles require GitLab Ultimate. Use a Security Manager, Maintainer, or Owner role for the group. Projects also need working CI/CD pipelines and eligible runners. Before enabling dependency scanning, confirm that each project contains a supported lockfile or dependency graph export, or can produce one through supported resolution or manifest fallback. A profile can't create meaningful coverage from an unsupported layout.
Apply the default profiles to the selected project
Use Advanced setup so the change applies only to the projects and scanners you choose:
- In the top bar, select Search or go to and open the group that contains the application project.
- In the left sidebar, select Secure > Security configuration, then select the Scanners tab.
- Select Enable scanners.
- Select Advanced setup, then Start advanced setup. Quick setup applies GitLab's default profiles to every uncovered project in the group, so it is too broad for this procedure.
- On Select projects, select the application project. Review the Scanner coverage column for any existing coverage. Advanced setup accepts up to 100 items.
- On Select scanners, select Static application security testing (SAST), Dependency scanning, and Secret detection. Choose the GitLab default profile for each scanner.
- On Review configuration, check the exact project, scanners, and profiles. Use the edit icons beside Items or Scanners to correct the selection.
- Select Apply configuration. GitLab applies profiles in batches, which can take several minutes. On the confirmation step, check each scanner, profile, and item count.
Applying a profile to a group selection attaches it to each selected project. Profiles aren't inherited through the group or subgroup hierarchy. Apply them explicitly to future projects.
The default profiles cover complementary events:
- SAST and dependency scanning run in merge request pipelines when commits are pushed to a branch with an open merge request, and in pipelines for the default branch.
- Secret detection runs in merge request and default-branch pipelines. Its default profile also enables push protection, which checks Git pushes in real time.
Attaching a profile doesn't create a historical result or prevent someone with sufficient authority from replacing it. Use the independently controlled verification steps below to assess who can alter or bypass required checks.
Align application tests with profile scanners
Profile-based scanners and application tests need to meet in the pipeline for the change being reviewed. A test job with no rules, only or except configuration is excluded from merge request pipelines by default, even when profile scanners run there. Include the application's tests explicitly so reviewers can inspect both results for the same source revision.
The following Node example assumes the project already has a reviewed package.json, a usable npm test script, and a committed package-lock.json. It also assumes the project can use an eligible GitLab-hosted Linux AMD64 runner with the saas-linux-small-amd64 tag and can pull node:22-alpine. The lockfile supplies the dependency versions for npm ci and dependency scanning. The example uses npm ci --ignore-scripts to avoid running package lifecycle scripts during installation. If the application's trusted build or tests depend on those scripts, adapt the install and test steps through the project's existing review path rather than silently omitting required setup.
Application test job alongside profile scanners
workflow:
rules:
- if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
- if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
- if: '$CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS && $CI_PIPELINE_SOURCE == "push"'
when: never
- when: always
stages:
- test
node_test:
stage: test
image: node:22-alpine
tags:
- saas-linux-small-amd64
script:
- npm ci --ignore-scripts
- npm test
rules:
- if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
- when: on_success
The first two workflow rules create merge request and default-branch pipelines. The third suppresses only a non-default branch's push pipeline when that branch already has an open merge request. This avoids a duplicate push pipeline without suppressing the MR pipeline. The final fallback retains ordinary branch pushes before an MR opens, along with tag, web, API, scheduled, and other pipeline sources. Review that fallback against any intentional exceptions in the existing configuration; it shouldn't weaken a rule that deliberately prevents a source from creating a pipeline.
Treat the YAML as a pattern to merge into the existing file, not as a replacement for it. Keep existing stages, jobs, include entries, variables, and source-specific rules. If the project already has workflow:rules, add the MR and duplicate-suppression behavior in the existing ordered rule set and check how the first matching rule affects every supported source. Add the explicit MR condition to each application job that needs to accompany the scanners. A job can't combine rules with only or except; either retain the team's established mechanism or translate its existing source restrictions into an equivalent ordered rules list before adding the MR condition. GitLab's workflow:rules documentation and job rules documentation explain ordering, duplicate pipelines, and source matching. Scanner selection still comes from the profiles in Secure > Security configuration > Scanners; don't copy scanner templates or profile settings into this application-job example.
Open an ordinary merge request and inspect the pipeline for its current head SHA. Confirm that the application test and SAST, dependency scanning, and secret detection jobs are present and individually successful, with the expected test output and scanner reports. Then merge through the normal review path and repeat those checks in the pipeline for the resulting default-branch SHA. Job selection before the MR opens can differ: an ordinary branch push can run the application test while the profile scanners wait for an MR or the default branch.
If the application test is missing but scanners are present, inspect the application's job-level rules, only or except clauses, declared stage and includes. If a scanner is missing while the application test runs, inspect the applied profile and its triggers, supported source or lockfile, and declared stages. For a job that exists but remains pending, check runner eligibility and tags; for a failed job, use its log to diagnose analyzer-image access, installation or execution errors. Fix the configuration at its source. An ordinary application change is enough for this check of job selection and execution.
Profile scanner jobs can use allow_failure: true, so the overall pipeline can remain green when a scanner fails. Inspect the expected job list, each scanner's status, and its report rather than inferring scanner execution from the pipeline status. A successful scan can still contain findings, and running the jobs together doesn't prevent a Maintainer from changing an application-controlled admission path. For checks that must block a merge, assess the admission decision and who can alter it.
To roll back a CI-only alignment change, revert the reviewed rules change through an ordinary merge request and confirm the next affected pipelines. Remove only the rules introduced for the alignment; preserve unrelated jobs, stages, includes, and intentional source gating.
Check configuration and scanner health
Use the next ordinary, reviewed application change to check the setup.
- Before relying on the profiles, review
.gitlab-ci.yml, included CI/CD configuration, security policies, and existing scanner settings. The wizard configures profile-based scanners; configuration supplied by CI/CD or a security policy must be changed at its origin. GitLab can show conflicting status when legacy and profile-based configuration coexist. Once the intended profiles and scope are confirmed, remove redundant legacy scanner includes through the normal review path if profiles will be authoritative. - Follow the pipeline alignment check for an ordinary merge request and the resulting default-branch revision. Confirm that the application test and selected scanner jobs are present and individually successful for the expected SHA. A job can complete successfully with no findings.
- Investigate an absent, skipped, or failed scanner job. Check its rules, supported languages and dependency files, runner eligibility, analyzer-image access, declared stages, and profile triggers. Dependency scanning needs scannable dependency data; a successful application build doesn't establish SCA coverage.
- After the next default-branch pipeline completes, return to Secure > Security configuration > Scanners. Review the Unprotected projects, Needs attention, and Stale scans cards, then select View details beside each scanner. Confirm the project, applied profile in Source, Status, and Last scan. A stale scan has been absent from at least three consecutive default-branch pipelines.
- You can also open Secure > Security inventory and review Test Coverage. Inventory evaluates pipeline-based coverage from the most recent completed default-branch pipeline. Push protection is event-based, so it can be active without a last-scan date.
Retain the selected profile names and project scope, source revision, pipeline URLs, and scanner job statuses. These records establish scanner activity for supported content at those revisions. A clean result doesn't prove that unsupported languages, out-of-scope dependencies, other branches, or a deployed artifact were examined.
See the Scanner Enablement Wizard for current prerequisites and behavior.
Interpret secret push-protection status
In the application project, open Secure > Security configuration > Security testing. Two parts of this page can describe secret push protection from different configuration sources:
- In Profile-based scanner configuration, open the applied secret-detection profile and inspect its triggers. Secret push protection: On means that profile contains the Git-push trigger.
- The separate Secret push protection card and project toggle report the legacy project setting. That card can say Not enabled while an applied profile supplies the Git-push trigger.
GitLab can enable push protection through either the project toggle or an applicable secret-detection profile with the Git-push trigger. An off legacy toggle alone therefore doesn't mean protection is disabled. The profile must be attached and available under the project's license. Instance availability, supported HTTP or SSH push handling, push and diff size limits, exclusions, and documented skip behavior also affect what is checked. See the secret push protection workflow and the security configuration profile documentation.
Use the profile details and project toggle to identify which configuration supplies protection. These settings describe whether eligible pushes should be checked; they don't demonstrate that a particular push was blocked or that every path is covered. Pipeline success doesn't establish push-time blocking either: push protection runs when Git receives a push, before pipeline jobs execute.
If the values appear contradictory, first confirm the profile attachment, trigger, license and relevant exclusions. Check the legacy toggle separately, and record which configuration source the project relies on. Use a controlled, non-production exercise only when the team needs runtime enforcement evidence; follow GitLab's documented workflow and avoid real credentials.
Change or remove a scanner profile
For a temporary project, return to the scanner's View details page, open the project's actions menu and select Disable profile-based scanning only for the profile you intend to remove. Recheck the project's configuration and preserve records needed for review. For a service you intend to keep scanning, review a replacement with the security owner before removing its current coverage. Disabling a profile doesn't remove pipeline scans supplied by another profile, CI/CD configuration, or a security policy. Removing the secret-detection profile also doesn't necessarily disable push protection supplied by the legacy project setting, another applicable profile, or instance enforcement. See configuring a scanner for projects.
Add DAP security review, triage and remediation
A scanner finding begins a security decision; it doesn't finish one. GitLab Duo can review changed code for logic flaws, assess whether a SAST finding is probably false, and prepare a merge request that attempts a fix. Keep those paths distinct because they need different human checks.
These security flows require GitLab Ultimate and the relevant GitLab Duo Agent Platform features. At the top-level group, an Owner turns on GitLab Duo and the Agent Platform, then enables Allow flow execution, Allow foundational flows, and the intended flows in Settings > GitLab Duo. Check the current foundational flow prerequisites and flow execution requirements, including an eligible runner.
Security Review starts from an ordinary merge request. For SAST triage and remediation, start with a successful supported scan and a real finding in the default-branch Vulnerability Report. Those flows act on ingested findings; they don't configure the scanner or establish its coverage.
Review business logic in the merge request
Security Review Flow reviews a merge request diff and context for logic-level weaknesses such as authorization gaps and information disclosure. It complements SAST; its findings aren't added to the Vulnerability Report or counted by merge request approval policies.
After an Owner allows Security Review and foundational flows, a Developer, Maintainer or Owner assigns Duo Security Review in the merge request's Reviewers section. The flow runs only when assigned; during the beta it doesn't automatically review every merge request and it consumes GitLab Credits.
When it completes, inspect the internal note for scope. On a private project, findings normally appear as diff threads with a CWE, severity, explanation and possible suggestion. Public projects receive findings in the internal note. Serious findings can set Request changes, but the flow never approves the merge request.
Treat each thread as a review prompt. Check the reported path against the application's authorization model, tests and expected data exposure. Mention @duo-security-review to ask a clarifying question, but a reply isn't a new full review. After a correction, assign Duo Security Review again. A human reviewer still decides whether the change is correct and whether the remaining risk fits policy.
Record the merge request SHA, flow note, threads and the corrected SHA. Large diffs might not be fully covered. A no-findings result isn't proof that the change is secure, and a Duo thread doesn't itself block or authorize a merge.
Triage SAST findings before asking for a fix
The SAST False Positive Detection Flow evaluates vulnerabilities produced by GitLab-supported SAST analyzers. It provides a confidence assessment, explanation and badge. This is analysis of a scanner finding, not the merge-request logic review described above.
For a project pilot, an Owner allows SAST False Positive Detection under the top-level group's Settings > GitLab Duo > Allow foundational flows. A Security Manager, Maintainer or Owner then opens project Settings > General, expands GitLab Duo, turns on Turn on SAST false positive detection, and saves. Configure push rules to permit the flow's service account. The user who initiates the flow opens their avatar menu, selects Preferences, finds the GitLab Duo section on the AI assistance tab if that tab is shown, selects the appropriate Default group, and selects Save changes; see Set a default GitLab Duo namespace. The project also needs an eligible runner and default-branch SAST results. Add and protect .gitlab/duo/agent-config.yml when the flow needs project-specific setup.
With the project setting enabled, a successful default-branch SAST scan automatically sends eligible findings for assessment. To analyze an existing finding, open Secure > Vulnerability report, select it, then select AI actions > Check for false positive. Authorized users can also run the flow on selected findings in the report.
Read the explanation alongside the finding, affected code, reachable call paths, tests and application context. The assessment doesn't justify dismissal on its own. A security professional should record the independent reason for confirming, dismissing or deferring the finding through the normal vulnerability workflow.
For an interactive second look, first confirm that the group has foundational agents turned on as described in the Security Analyst Agent prerequisites. Open the GitLab Duo sidebar, select Add new chat, choose Security Analyst, and give it a specific vulnerability ID or URL. For example: “Assess whether this SAST finding is reachable, explain the likely impact, and list the code and runtime assumptions a reviewer should verify.” The agent can help interpret scanner context, EPSS and reachability. It is a chat assistant for investigation; it is not Security Review Flow and doesn't review the merge request as an assigned reviewer.
Review a proposed fix as an ordinary change
Agentic SAST Vulnerability Resolution uses repository context to propose a source fix. At the top-level group, allow both Resolve SAST Vulnerability and SAST False Positive Detection. Configure push rules to permit the flow's service account. The user who initiates the flow opens their avatar menu, selects Preferences, finds the GitLab Duo section on the AI assistance tab if that tab is shown, selects the appropriate Default group, and selects Save changes; see Set a default GitLab Duo namespace. The project also needs an eligible runner. Add and review .gitlab/duo/agent-config.yml when the flow needs build or test setup that it can't infer safely.
Automatic resolution begins after a successful default-branch SAST scan. It considers eligible findings from supported analyzers after false-positive analysis. When it can produce a fix, it opens a merge request and runs its pipeline. To start it manually, open the vulnerability in Secure > Vulnerability report and select Resolve with Agentic AI.
The merge request is a proposed remediation, not a verified outcome. Review the diff for behavior changes and new trust assumptions. Confirm its pipeline and security scan completed for the head SHA, inspect whether the finding is absent from that result, and run focused tests. Use the project's normal reviewers, approval rules and protected-branch path. The flow doesn't approve or merge its proposal, and a passing pipeline doesn't establish production remediation.
For vulnerable dependencies, dependency scanning auto-remediation is a separate beta path. Its generated jobs are untagged, require privileged mode and don't use the project's .gitlab-ci.yml. Review runner and service-account permissions, then assess each proposed version bump normally.
Apply the journey consistently across projects
For broader rollout, security configuration profiles can separate scanner configuration from the Automated triage and remediation profile for false-positive detection, SAST resolution and dependency remediation. Pilot the documented per-project settings above first. When moving to profiles, choose a preset that fits reviewer capacity and use the documented GraphQL API to apply it; don't assume the profile has an equivalent UI action.
Profiles make rollout consistent, but they don't make results authoritative. Verify that the expected scan and flow ran and that any proposal passed human review. Keep merge enforcement, reviewer independence and release authorization in the separately protected controls below.
Make trustworthy verification part of delivery
Scanner results and agent reviews give authors useful feedback. Required checks also need to affect the decision to merge or release a change. That decision needs to account for the source revision or content identity, target branch and relevant target state, rules and scanner versions, results examined, decision made, and events that invalidate that decision. A green pipeline by itself doesn't show that a required check ran, covered the relevant files, used trusted inputs, or produced the result being admitted.
Put checks where they can change the outcome. Early feedback helps an author fix a problem while the change is still familiar. Default-branch and scheduled scans can catch weaknesses missed earlier or disclosed later. When a check is required, its result needs a trustworthy path into the merge or other admission decision.
Where enforcement matters, treat the application Maintainer as untrusted for that particular decision. The policy owner or verifier therefore needs authority outside the application path. Check whether the application actor can change policy selection, scanner configuration, rules, variables, runner execution, report contents, approval eligibility, merge settings, branch protections, or another route to the target.
GitLab security policy projects can separate policy management from application projects and apply policies through namespace relationships.1 That separation is useful only when effective permissions preserve it. Inherited roles matter, as do the people allowed to link, unlink, or manage the policy relationship. Start at Secure > Policies in the project and its parent namespaces. Review security policy project enforcement with the namespace owners, then test the paths available to the application Maintainer.
Merge request approval rules can support independent review, but the rule, eligible approvers, reset behavior, and alternate write paths all affect the outcome.2 A named reviewer isn't independent if the application actor can add another eligible approver, change the rule, push directly to the target, or satisfy the decision through a credential with equivalent authority. Use the merge request approvals documentation to identify the product behavior, then check it in the namespace and role model you actually use.
Inspect project approval defaults in Settings > Merge requests > Merge request approvals, then compare them with the rules on the actual merge request. Inspect the target's branch rules in Settings > Repository > Branch rules. Include every matching rule and its source; a single restrictive entry doesn't establish the effective permissions.
For every control you intend to rely on, compare a permitted result with a prohibited one. First show that a legitimate clean change can complete the intended path. Then attempt a representative bypass through that same admission path and confirm that the target remains unchanged. Make sure an unrelated failure didn't cause the denial. If a request times out, reconcile its result before treating it as a denial or retrying a possible write. Include the alternate update paths found during the permission review; testing only the merge button says little about direct pushes, force pushes, tokens, integrations, or privileged automation.
If a prohibited change reaches the target, restrict the affected authority and correct the cause before relying on the control. When a result is missing or a request has an uncertain outcome, reconcile the state before continuing. After the correction, check that legitimate work still succeeds.
Code review and security verification answer different questions. A risk exception may authorize proceeding despite a known problem, but it doesn't satisfy the Standard's unwaivable Verify outcome. Record the exception's owner, reason, compensating action, expiry and recheck trigger.
Scanner profiles, DAP flows and separate policy ownership do not by themselves provide a complete merge gate resistant to an application Maintainer. Keep that requirement open when assessing the workflow's authority. The release example below teaches artifact identity and deployment authorization separately; it doesn't supply the missing admission control.
Before following the separate release walkthrough, record exactly what the selected application's Verify work accepted: the source SHA or content identity, target state, required scanner jobs and reports, DAP or human review, policy revision and decision owner. Then identify who can connect that accepted result to the application's actual merge and release path. If an application Maintainer can alter or bypass that connection, or if no supported connection exists, keep the Verify-to-Release prerequisite open. A green pipeline, named approver or signed artifact can't replace an independent admission design that preserves the same untrusted-Maintainer model.
Notes
-
Security policy projects and their enforcement features are available in GitLab Ultimate across GitLab.com, Self-Managed, and Dedicated. See Security policy projects for current prerequisites, permissions, inheritance, and ownership behavior. ↩
-
Required merge request approvals are available in Premium and Ultimate. GitLab Free supports optional approvals, which don't block merging. See Merge request approvals for current behavior and availability. ↩