Restrict Duo Code Review foundational flow to protected branches only

Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.

Title: Restrict Duo Code Review foundational flow to protected branches only

Summary

Today, the Duo Code Review foundational flow (code_review/v1) can be used for merge requests regardless of whether the target branch is protected. This issue proposes adding branch-level controls so that organizations can restrict Duo Code Review to protected branches only (for example, main, release/*), aligning AI-powered reviews with existing compliance and change-management policies.

Problem to solve

Many customers have strict controls around:

  • Which branches are considered trusted / production-facing (typically protected branches).
  • Where automated or semi-automated changes and reviews are allowed.
  • How compliance and audit expectations map to branch protections.

The Duo Code Review foundational flow is configured and enabled at the project/group level (via AI Catalog foundational flows) and is used by the Code Review workflow service to kick off code_review/v1 for a merge request.

However, there is currently no way to say “only allow Duo Code Review when the MR target branch is protected”. This leads to a few issues:

  • Risk/compliance: AI-powered review could run on MRs targeting unprotected branches that bypass existing approval / change-control workflows.
  • Policy misalignment: Many orgs want to centralize trust on protected branches, not on per-project enable/disable toggles.
  • Operational clarity: Without branch-based scoping, it’s harder to explain to auditors and internal security teams exactly where Duo is allowed to participate in review.

Proposal

Add branch-level scoping for the Duo Code Review foundational flow (code_review/v1), so administrators can ensure it only runs where it’s appropriate.

Concretely:

  1. New configuration option

    At group and project level (where Duo foundational flows are configured today), introduce configuration for eligible target branches for Duo Code Review, for example:

    • Simple version:
      • Boolean: “Only allow Duo Code Review for MRs targeting protected branches”
    • More advanced (future iteration):
      • Allow a branch pattern list: e.g. main, release/*, hotfix/*.

  2. Behavioral changes

    When a user or workflow attempts to start Duo Code Review on a merge request:

    • If the MR target branch is protected and matches configuration:
      • No change in behavior – code_review/v1 runs as today via ReviewMergeRequestService and the API endpoint that orchestrates comment creation.
    • If the MR target branch is not protected (or outside allowed patterns):

      • The Duo Code Review request is rejected with a clear error, similar to how missing foundational flows and permissions are handled today (for example, using existing error messaging patterns like foundational_flow_not_enabled_error).

      • In the UI, show an informative message such as:

        Duo Code Review is restricted to protected branches for this project. The target branch <branch> is not eligible.

  3. Where to enforce

    • Duo Code Review service layer:
      • Ai::DuoWorkflows::CodeReview::ReviewMergeRequestService already calls into the code_review/v1 foundational flow and checks enabled flows for the project; extend this logic to also check a “protected-only” / branch-eligibility rule before starting the workflow.
    • API guardrails:
      • The API::Ai::DuoWorkflows::CodeReview endpoint already vets access, composite identity, and that foundational flows are enabled; it should also reject requests where the target branch does not meet the configured eligibility criteria.

Intended users

  • Primary

    • Security & compliance teams
    • Platform / infra teams that manage branch protection and approval rules

  • Secondary

    • Developers and maintainers who trigger Duo Code Review on MRs

Use cases & examples

  1. Highly regulated environments

    The organization only wants AI-involved review on changes that target main or release/*, where additional human approvals, checks, and audit logging are already enforced via branch protections and approval rules.

  2. Multi-branch development workflows

    Teams work on long-lived feature branches; they’re comfortable with Duo Code Review on integration branches like develop, but not on ephemeral or experimental branches.
    Admins can configure protected branches and then enable Duo Code Review only when an MR is targeting those branches.

  3. Gradual rollout of Duo Code Review

    Start by allowing Duo Code Review only for a small set of protected branches, evaluate behavior and risk, and then optionally expand scope.

Proposal details / UI ideas

Configuration surface

  • Group-level settings (applies to subgroups/projects that inherit foundational flow settings):

    Under Settings → General → GitLab Duo, where foundational flows are configured, add a new section for Duo Code Review:

    • [ ] Restrict Duo Code Review to protected target branches only
    • (Future) Optional list of additional branch patterns (for example, text area or small rule builder).

  • Project-level settings

    Mirror the group-level option, allowing:

    • Inheritance from group.
    • Local override (“use group setting” vs “custom setting”).

Runtime behavior

When ReviewMergeRequestService starts a workflow for code_review/v1, it checks:

  • merge_request.target_branch
  • Whether it is protected in the project.
  • Whether the configuration option is set to “protected-only”.

If not eligible:

  • Do not start the foundational flow.
  • Return a structured error (for both UI and API consumers) indicating that Duo Code Review is restricted to protected branches for this project/group.

Alternatives considered

  • Rely only on per-project enablement of code_review/v1 via AI Catalog item consumers.
    • This is too coarse; customers want policy aligned with existing branch protection semantics, not just all-or-nothing at the project level.
  • Rely on approval rules alone:
    • Approval rules govern who can approve, not whether Duo Code Review can even run or suggest changes on a given branch.

Permissions & security considerations

  • This change tightens where Duo Code Review is allowed to run; it should not introduce new capabilities.
  • It should respect:
    • Existing Duo foundational flow enablement (for example, duo_foundational_flows_enabled, enabled_flow_catalog_item_ids, etc.).
    • Existing composite identity and access checks in the Code Review API.
  • Audit/logging behavior remains as-is; this only adds an early “gate” based on target branch protection status.

How this fits into existing architecture

  • Foundational flow definition:
    • code_review/v1 is defined as a GA foundational flow in Ai::Catalog::FoundationalFlow, with ai_feature: "review_merge_request" and a description focused on streamlining code reviews.
  • Runtime orchestration:
    • ReviewMergeRequestService invokes ::Ai::Catalog::FoundationalFlow['code_review/v1'] and starts a workflow via CreateAndStartWorkflowService for a given merge request.
    • The Code Review API validates that the flow is enabled and correctly wired for the project and service account.

This proposal adds an extra branch-eligibility check before the workflow is started, leveraging the project’s protected branch configuration.

Acceptance criteria

Configuration

  • Add a “Restrict Duo Code Review to protected target branches only” setting at group and project level (where foundational flows are managed).
  • Group-level setting can be inherited or overridden at the project level.

Behavior

  • When the setting is enabled and an MR’s target branch is not protected, any attempt to start the code_review/v1 foundational flow:
    • Fails early with a clear, user-facing error in UI and API.
    • Does not start a workflow in Duo Agent Platform.
  • When the setting is enabled and an MR’s target branch is protected, Duo Code Review works exactly as today.
  • When the setting is disabled (default), behavior remains unchanged.

Safety & telemetry

  • Add internal event(s) or metrics for “Duo Code Review blocked due to branch restriction” for observability.
  • Ensure existing error-handling paths (for example, foundational_flow_not_enabled_error) are reused or extended so users get consistent messaging.

Labels (suggested for triage)

  • type::feature
  • devops::ai-powered
  • section::ai
  • group::agent foundations
  • Category:Duo Agent Platform
Edited by 🤖 GitLab Bot 🤖