## Problem Today, GitLab's code review workflows treat all MRs with the same level of scrutiny by default. Teams that want to differentiate must configure it manually through CODEOWNERS and branch protection rules, and those match on file paths, not on semantic risk. A safe refactor touching 50 files gets the same review requirements as a 3-line change to an authentication critical path. Low-risk MRs sit in queues blocking engineers who need to ship, while high-risk MRs don't get enough attention because that same queue pressure means reviewers can't give them the depth they deserve. As AI-assisted development accelerates code production, this gets worse: teams create more MRs than humans can reliably review. The instinct is to jump straight to fixing this by routing MRs differently based on risk. But routing assumes we already know which MRs are risky, and today nobody does, reliably. Before anything can be safely automated on top of a risk judgment, that judgment has to exist, and it has to be visible and trustworthy enough for reviewers to rely on it. This epic is scoped to that first step: producing a risk level for every MR, with a clear rationale behind it. Acting on the risk level, deciding what happens as a result, is deliberately a later step. See [Tiered Review Routing (23591)](https://gitlab.com/groups/gitlab-org/-/work_items/23591). ## Terminology This is the shared vocabulary for this epic and all its phases. It is deliberate: "tier" is not used anywhere in this epic, because tiering is a routing concept and routing is out of scope here. | Concept | Name | Notes | |---|---|---| | The feature | MR Risk Assessment | | | The process that runs on an MR | risk assessment (verb: assess) | Runs once, at MR open or ready-for-review | | Weighted numeric output | risk score | Internal, not surfaced to users | | Categorical output | risk level: Low / Medium / High / Critical | What users see, what domain gates floor | | Matched risk domains | domain tags | Flow downstream to specialized agents | | Uncertainty qualifier | confidence | Surfaced alongside the risk level | | Engineering-only terms | classifier, classification, rubric | Code and engineering docs, never user-facing copy | | Reserved for later | review level, routing | Belongs to the routing epic, not this one | ## Proposal An agent-driven system that evaluates each MR and assigns a risk level. It runs once, in parallel with base Duo Code Review, at MR open or ready-for-review time. It does not re-run on re-review requests and does not use the Duo Code Review output as input. | Risk level | Meaning | |---|---| | Low | No unusual risk signals detected | | Medium | Some risk signals present, standard scrutiny warranted | | High | Significant risk signals or a domain gate floor | | Critical | Highest-sensitivity domains, for example cryptography or payments | The risk level is explainable. Every assessment surfaces a plain-language rationale, for example "High risk because this MR modifies `/ee/lib/auth/session_token.rb` and affects 4 downstream API consumers", so reviewers can act on it or challenge it. In this epic, the risk level is informational. Nothing is gated, blocked, or auto-approved on the basis of it. ## Risk Assessment Signals **Semantic signals (highest weight)**: Changes to authentication, authorization, session, or encryption logic. API contract or schema modifications (breaking change detection). Blast radius: number of services/consumers affected, using Orbit's CALLS/DEFINES graph when available and path-pattern heuristics as a fallback. Behavioral vs. cosmetic change detection. Change dispersion, whether changed files are logically related or scattered across unrelated subsystems. **Structural signals**: Files changed are in security-sensitive directories, for example `ee/`, `config/`, `.gitlab-ci.yml`. Cross-repo or cross-service impact detected. Changes to shared libraries or platform-level code. **History-based signals (GitLab-native advantage)**: SAST/DAST findings in the affected code paths. Pipeline failure rate on the affected files. Deployment frequency and incident history for the affected area. Prior review patterns. Author commit history on changed files. Existing test coverage on changed lines, not only whether test files were modified alongside the change. **Code generation signals**: MR was authored primarily by an AI coding assistant, detected via service account author patterns. Future: per-source track record, weighting by the incident/revert history of the specific AI tool or workflow that produced the MR rather than treating all AI-generated code identically. ## Domain Gates Certain domains carry enough inherent risk that they establish a minimum risk level regardless of rubric score. Domain gates are a pre-scoring categorical override layer: they are not inputs to the weighted rubric, they override it. When a gate fires it emits a `domain_tag` and a minimum risk level. The final risk level is `max(rubric_risk_level, domain_floor)`. Multiple gates can fire on one MR. | Domain | Detection | Minimum risk level | |---|---|---| | Auth / session / authorization | Semantic + path patterns | High | | Database migration | `db/migrate/`, `.sql`, migration class patterns | High | | Cryptography / secrets | `cipher`, `encrypt`, `kms`, `vault`, secret management patterns | Critical | | Payment processing | Semantic patterns (`stripe`, `billing`, `charge`, PCI-scope) | Critical | | Compliance / audit / PII | `audit_event`, data retention, PII handling patterns | High | | Infrastructure / deployment | `Dockerfile`, `*.tf`, `k8s`, `.gitlab-ci.yml` | High | **Configuration.** GitLab ships platform defaults. Groups can override thresholds or add domains at group level. Projects can register custom domain gates using CODEOWNERS-style rules, path patterns plus semantic keywords, with a declared minimum risk level. **Downstream use.** `domain_tags` produced here flow to [Advanced Duo Code Review / Specialized Agents (21524)](https://gitlab.com/groups/gitlab-org/-/work_items/21524), where they determine which specialized agents are recommended. Consuming them for routing is scoped to the routing epic, not this one. ## Key Behaviors - **Runs once**: fires at MR open or ready-for-review, in parallel with base Duo Code Review. Does not re-run on re-review requests, new commits, or draft state changes. - **Staleness indicator**: when new commits are pushed after assessment, the existing note shows which diff version was assessed and how many commits have been added since, for example "Risk assessed against diff v3, 2 commits added since". Re-evaluation on update is explicitly out of scope. - **Break-glass override**: a human can override the risk level with a required written justification. Because nothing is gated on the risk level in this epic, an override is purely a correction of the assessment and is logged as calibration signal rather than as a policy decision. - **Confidence surfacing**: the assessment includes a confidence level. A borderline Medium/High assessment is surfaced differently from a clear-cut one. - **Configurable thresholds**: teams can tune what constitutes High risk for their codebase. Custom domain gates are the primary mechanism. ## Why This Is a GitLab Differentiator External AI code review tools are largely constrained to the diff and repository graph. Duo has access to CI/CD history on affected code paths (pipeline failure rates, flaky tests), SAST/DAST findings from prior MRs to the same files, deployment frequency and incident data, issue and milestone context, review history, and the Orbit knowledge graph for blast radius. Leading context engines in this space reportedly achieve around 80% classification accuracy using codebase context alone [figure needs a source before it is used externally]. GitLab's access to CI/CD, security scan, and incident history on top of that context is the differentiator worth validating. ## Out of Scope Acting on the risk level is out of scope: no auto-approve, no fast-track merge, no approval-policy gating, no auto-merge restrictions, no recommendation of a review depth. That work is [Tiered Review Routing (23591)](https://gitlab.com/groups/gitlab-org/-/work_items/23591). Re-evaluation on push is also out of scope. ## Open Questions - How do we handle the cold-start problem for new projects with no review history? - How do we expose calibration data to platform admins so they can see where the model is wrong? - Should the risk level be visible to the MR author, or only to reviewers? - Should domain tags be surfaced in the MR UI similar to labels, or only through the internal assessment note? - At what point does Orbit indexing become a prerequisite rather than optional enrichment for blast radius scoring, and what is the accuracy difference when falling back to path-pattern heuristics? - With nothing gated on the risk level, what is a reviewer meant to do with a High risk level? Even if the answer is "nothing yet, we are calibrating", the epic should say so. - Should the code identifiers that currently use "tier" (`effective_tier`, `RiskTierOverride`, `OverrideTierService`, the `effectiveTier` GraphQL field) be renamed to match, or is "tier" retained in code?