Document trigger-based setup for DAP reviewer assignment

Rewrites automatic_reviewer_assignment.md for the trigger-based setup. The page now has one procedure - create the trigger - with turning the Recommend Reviewers flow on for the top-level group as a prerequisite, matching how the other foundational flow pages are written. The old Reviewer assignment strategy section documented a setting that !248476 (merged) has now removed, so the page on master is currently wrong - and it never had trigger instructions at all.

Two behaviours are documented for the first time, verified in code and live: reviewers are assigned only on a draft-to-ready transition (a real narrowing versus the bespoke path, which also covered merge requests opened non-draft), and the assignment is attributed to the Recommend Reviewers flow's service account, inherited from the top-level group, rather than the person who marked the merge request ready.

• Also links the flow from the foundational flows list and the Agent Platform feature tables, so it is findable by name.
• Related to #607680 (closed) · Epic: gitlab-org#23019
• Technical Writing review required
• Two claims from the issue could not be verified and were left out - see the detail block, both need a decision

Detailed context for AI agents

What changed

The strategy section is replaced with the trigger path as a single Use the flow procedure. Turning the Recommend Reviewers flow on for the top-level group is a prerequisite that links to turn foundational flows on or off, rather than a second copy of those steps on this page. The candidate ranking explanation (availability, workload, local time, recent activity) is kept verbatim, because that behaviour doesn't change.

I corrected the UI wording against the actual docs and code rather than the issue text:

Issue said	Actual
Automate > Triggers	AI > Triggers
Merge request > Marked ready	Conditions > Add condition > On an event, then Event = Merge request and Run when = Marked ready

The flow's display name is Recommend Reviewers and feature_maturity: "beta" (ee/app/models/ai/catalog/foundational_flow/definitions/recommend_reviewers.rb), so the section carries a {{< details >}} block with Status: Beta. The old > [!flag] block had to go regardless: dap_powered_recommend_reviewers is deleted in !248482 (closed). The history keeps both the flag's introduction and its removal, so a reader on an older docs version can see where the flag went. The flag was only ever used internally.

Two behaviours documented for the first time

Both verified in code and confirmed live, not taken on faith:

1. Reviewers are assigned only on a draft to ready transition. MergeRequests::ReadyEvent is published from publish_draft_change_event with return if new_draft_status, so it fires only for that transition. The bespoke path also covered merge requests opened non-draft, via ReloadMergeHeadDiffService and PendingInitialAssignment. So this is a genuine narrowing of coverage in Beta, not a doc gap, and the page previously claimed the opposite. Linked to issue 592452, which closes the gap at GA.
2. Attribution and permissions. The assignment and its note come from the Recommend Reviewers flow's service account, inherited from the top-level group, not the person who marked the merge request ready. That person needs at least the Developer role: set_merge_request_metadata requires admin_merge_request, which config/authz/roles/developer.yml grants at Developer.

Notes for review

• I deliberately did not document a specific failure mode for the permission case. The issue asked me to state that a run "silently assigns nothing" for an under-privileged ready-marker, but #607675 (closed) is still workflow::refinement, and the flow's behaviour on a permission-denied API call isn't something I could verify from this repo. The page says reviewers are not assigned, which is accurate and doesn't over-claim. If #607675 (closed) concludes something more specific, this needs a follow-up.
• The issue also asked me to document that "automation/bot-marked-ready MRs do not trigger the flow". I left it out - I could not find code supporting it, and I have not tested it live either. MergeRequests::ReadyEvent is published for whichever user performs the transition, with no bot exclusion, and the trigger worker has no bot check. Documenting it would have meant asserting behaviour I couldn't verify. Please confirm whether that claim is real; if it is, I've missed where it's enforced.
• doc-locale/ja-jp and ko-kr still carry the old section. Those are machine-synced by the TW tooling, so I left them.
• The description: frontmatter still reads "Automatically assign Code Owners as reviewers when a merge request is ready", which was already incomplete before this MR. Left alone to keep the diff to the section in question, but happy to widen it.

Technical writing review

Review by Uma Chandran. All suggestions applied, with two deliberate departures:

• The Service account step was not re-added. GitLab Duo Code suggested rewording it, but it had already been deleted on purpose: the field only renders when a trigger points at a config file, and the model rejects a trigger carrying both a service account and a catalog flow. That comment was on a stale revision.
• The prerequisite link path was corrected. The suggested ../../../_index.md#prerequisites resolves to doc/user/_index.md from this page; it is now ../../../duo_agent_platform/_index.md#prerequisites.

Two review questions answered:

• Did anyone use dap_powered_recommend_reviewers? Internal use only. The history entry now records the flag and its removal rather than dropping all mention of it.
• One note, or one per approval rule? One note per merge request. The wording says so.

One assumption worth a second look. On doc/user/duo_agent_platform/_index.md the flow is listed under Beta and experimental features that don't consume credits, on Premium and Ultimate. That is inferred from there being no unit primitive or pricing config for recommend_reviewers in this repo, so the credits work from https://gitlab.com/gitlab-org/gitlab/-/issues/599103 looks unfinished. If it does consume credits, the row belongs in the beta-with-credits table instead.

Still open on this MR and unrelated to the docs: whether the .com flag needs rolling out for Beta in %19.4.

Rebase history

• Originally targeted !248476 (merged) so the docs and the setting removal would land together. That merged on 2026-08-20, so this now targets master directly and the parent's commit has been dropped from the branch.
• Rebased earlier after master's b7e0a6dd223e ("Narrow any-approver reviewer candidates to those who can merge") added a paragraph to this page describing how candidates are chosen for the default All Members rule. That behaviour is independent of setting-versus-trigger, so it still applies and is preserved in the rewritten section. Master's c16c4c9d4e85 also simplified ../../../../user/duo_agent_platform/… links to ../../../duo_agent_platform/… in this file; the new prose follows that convention.
• The trigger form changed under this MR while it sat in draft: it now builds a list of conditions rather than taking a flat event type. The Create the trigger steps were updated to match, mirroring the wording on triggers so the two procedures agree. Confirmed against flow_trigger_conditions.vue, flow_trigger_condition_form.vue, and event_actions_configuration.vue.
• Those Create the trigger steps were corrected again after testing them against the real UI. Three things were wrong:
  • The steps told the reader to pick a Service account. That field only renders when the trigger points at a config file - when it points at a catalog flow it's hidden, and the model rejects a trigger that carries both (validates :user, absence: true, if: :ai_catalog_item_consumer in ee/app/models/ai/flow_trigger.rb). The step is deleted, not reworded - the service account is inherited from the flow's configuration on the top-level group.
  • The step order was wrong. The real form is Description, then a Target section holding Configuration source and the flow picker, then Conditions. The docs had Conditions first. Confirmed against ee/app/assets/javascripts/ai/duo_agents_platform/pages/flow_triggers/components/flow_trigger_form.vue.
  • "AI Catalog" is not a UI label. The Configuration source radio reads Flow or external agent and Configuration path, and it's hidden entirely unless the user can create third-party flows, so the step is now worded to work either way.
• The reviewers-already-present limitation was dropped from the page by decision - runs are wanted even when reviewers exist.

Testing

vale and markdownlint pass with 0 errors and 0 warnings after the rebase. Every relative link and anchor was re-checked against current master, including the two new cross-links and the new duo_agent_platform/_index.md#prerequisites anchor: duo_agent_platform/_index.md, duo_agent_platform/flows/foundational_flows/_index.md#turn-foundational-flows-on-or-off, duo_agent_platform/flows/foundational_flows/_index.md#service-accounts, duo_agent_platform/triggers/_index.md, and policy/development_stages_support.md#beta-features all resolve.

Live verification

Also tested live on gitlab-com/create-stage/code-review-ai-experiment-playground via the API on 2026-08-21, after finding the wording issues above:

• Created the trigger exactly as documented (event type 4 = merge_request_ready, pointed at the Recommend Reviewers catalog item consumer, no service account supplied). It resolved the service account to duo-recommend-reviewers-gitlab-com on its own, which is what confirms the service account is inherited rather than chosen on the trigger.
• Marking a draft merge request ready produced exactly one recommend_reviewers/v1 run, a reviewer assigned about 45 seconds later, and one rationale note - all posted by duo-recommend-reviewers-gitlab-com, not by the person who marked it ready.
• A control merge request opened directly in a ready state produced no recommend_reviewers/v1 run and no reviewer assignment, confirming the draft-to-ready-only claim live, not just in code.
• One caveat, not a docs issue: the playground project still had the old reviewer_assignment_strategy: dap_powered setting on. !248476 (merged) closes the write path but deliberately leaves existing rows and the worker branch alone, so both the old bespoke path and the new trigger fired, producing two flow runs and two duplicate rationale notes on the same merge request. Any project that already opted into the beta setting and then adds the trigger will see this, until the setting is switched to disabled. Flagging this for the rollout - it isn't something this docs MR fixes.

MR acceptance checklist

• Page describes trigger-based setup with no reference to the removed setting
• Beta limitation on ready-on-create merge requests documented explicitly
• Attribution and Developer-role requirement documented
• Follows the documentation style guide