Docs: clarify MRAP target-branch comparison pipeline selection
What does this MR do and why?
Documents behaviour that governs which pipelines can serve as the target-branch baseline for a merge request approval policy (MRAP). Today the docs describe the inputs to the comparison (supported pipeline sources, child pipelines) but not the selection algorithm — which order commits are considered in, how many pipelines are examined per commit, and how security_orchestration_policy-sourced (scheduled scan execution policy) pipelines participate.
The gap has surfaced repeatedly in support tickets on busy default branches. Customers observe that their scheduled SEP pipeline exists and is complete, yet does not appear in the MRAP bot's target-branch comparison, and there is no documentation to explain why. This MR adds that explanation.
Changes:
-
### Scope of merge request approval policy comparison— adds a new#### How the target-branch comparison pipeline is selectedsubsection covering:- The candidate order: merge base →
start_sha→ ten most recent commits on the target branch. - The ten newest completed pipelines per commit cap on candidate selection (
MAX_CHECKED_PIPELINES_FOR_SECURITY_REPORT_COMPARISON). - That
security_orchestration_policy-sourced pipelines are not eligible as baseline candidates; they can only join via the same-commit expansion step (step 4) when they share a SHA with the baseline. - A short "Implications for busy default branches" subsection with the three practical mitigations (top-level
workflow:rules over job-levelrules:; rebase; ensure scans run on every target-branch pipeline).
- The candidate order: merge base →
-
### security_report_time_window— adds one paragraph noting that the time-window look-back also filters on standard CI sources, so widening the window cannot fall back to a scheduled SEP pipeline. Cross-references the selection section.
Related issues
- Related: #627809 (behaviour + docs improvement request; this MR addresses the docs portion).
- Context: #525509 (closed) (introduced
security_report_time_window; did not document theci_sources-only look-back). - Context: #455760 (closed) (precedent: the same 10-per-SHA cap was addressed for
license_findingin 17.5).
Screenshots or screen recordings
N/A — text-only documentation change.
How to set up and validate locally
- Check out this branch.
- Render
doc/user/application_security/policies/merge_request_approval_policies.mdlocally (for example, withbundle exec rake docs:previewingitlab-docs, or by inspecting the Markdown directly). - Confirm the new
#### How the target-branch comparison pipeline is selectedsubsection appears under### Scope of merge request approval policy comparison, and the extra paragraph appears under### security_report_time_window. - Confirm the cross-reference from
security_report_time_windowto the selection section renders as a working anchor.
MR acceptance checklist
Please evaluate this MR against the MR acceptance checklist. It helps you specify, review, and community-review changes based on Product Development Flow.