<!--IssueSummary start--> <details> <summary> Everyone can contribute. [Help move this issue forward](https://handbook.gitlab.com/handbook/marketing/developer-relations/engineering/community-contributors-workflows/#contributor-links) while earning points, leveling up and collecting rewards. </summary> - [Label this issue](https://contributors.gitlab.com/manage-issue?action=label&projectId=278964&issueIid=633112) </details> <!--IssueSummary end--> ## Background - An AI flow trigger can start a flow when a work item status changes, with a `status.name` filter on a `work_item` trigger. - Nothing moves the work item to the next status when that flow finishes. Generate Workplan and Duo Developer set no status, and they cause no event when they finish. - So a status-driven chain of flows needs a human at each stage, or a custom flow that only sets the next status. - GitLab already has the facts that it needs at the end of a session. - The workflow records the trigger that started it (`trigger_flow_trigger_id`). - The workflow records its work item (`issue_id`). - `Ai::DuoWorkflows::WorkflowFinishedCloudEvent` publishes the finish. Row 2 of https://gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist/-/work_items/3074 asks Generate Workplan to set a configurable next status. This proposal gives the same result for every flow that a trigger starts. ## Proposal Add two settings to `Ai::FlowTrigger`: | Field | Type | Effect when a session that the trigger started finishes | |---|---|---| | `status_on_finish` | text, a status name | GitLab moves the work item of the session to this status. | | `ready_merge_requests_on_finish` | boolean, default `false` | GitLab takes the Draft merge requests that the session created out of Draft. A project with automatic Duo Code Review then starts a review. | Behaviour: - A subscriber to `WorkflowFinishedCloudEvent` applies the settings. It acts only on a session that reached `finished`. A stopped session, a failed session, or a session that waits for input changes nothing. - The subscriber writes as the composite identity of the session, with the session as the workflow of the request. So the status change is a flow-caused event, and the existing rules decide if the next trigger fires: - the flag `allow_flow_originated_cloud_event_triggers`; or - the flag `ai_flow_trigger_chaining`. The finished session becomes the parent of the next session, inside the depth and breadth limits of the chain. - The subscriber writes nothing when the work item left the status that the trigger filters on while the session ran. A human who moves the work item keeps control. - The status is a name, as in the `status.name` filter. So one trigger works with the lifecycle of each work item type. - The subscriber finds the merge requests through the `created` merge request links of the session. - GraphQL: `statusOnFinish` and `readyMergeRequestsOnFinish` on `aiFlowTriggerCreate`, `aiFlowTriggerUpdate` and the trigger type. - The settings apply only to a trigger with the `work_item` event type. The model rejects them on other triggers, and the worker changes nothing for a session that a mention or an assignment started. - The settings move a work item from the status that the trigger filters on to the next status. - A session does not record if the "created" or the "status changed" action started it. - So the backend checks the event type, and the UI shows the fields only for "Status changed". - A new `wip` feature flag gates the behaviour. Example lifecycle, with no flow between the stages: | Trigger | Filter | Flow | `status_on_finish` | `ready_merge_requests_on_finish` | |---|---|---|---|---| | A | status `Planning` | Generate Workplan | `Ready for development` | `false` | | B | status `Ready for development` | Duo Developer | `In review` | `true` | Human checkpoint: to keep a human decision between two stages, set `status_on_finish` to a status that no trigger listens on, for example `Plan ready`. A human then moves the work item to the status that starts the next stage. The status that starts the next stage must not be the `status_on_finish`, because a status that does not change causes no event. Alternatives considered: - **A custom hand-off flow for each stage.** It must find out from side effects which flow finished, on which work item, and how. It runs one CI job for each event, and it uses one level of chain depth for each stage. Its checks are also weak. A merge request that a flow opens has the human as its author. So an author check cannot tell it apart from a merge request of the human. - **A tool that each flow calls at its end.** The model decides if the run is complete. The prompt of each foundational flow must change. - **The trigger goal** (https://gitlab.com/gitlab-org/gitlab/-/work_items/627896). A foundational flow takes no goal from the trigger (`accepts_trigger_goal` is `false`). The model must read the status name out of prose. - **Keep a human status change between the stages.** This is the current way. It needs no change, but a human must act at every stage. The proposal keeps this possible, see "Human checkpoint" above. - **An automated write that GitLab records as made by the human, not by the session.** GitLab sets the status when the session finishes, but shows the human as the actor. The next trigger then sees a human change, so it fires without the flow-originated flags. This option is not acceptable: - It removes every bound on loops, because no chain limit applies to a human change. - The status history and the audit events show a change that the human did not make. - It goes against the rule that AI-generated writes use composite identity. ## Plan This feature ships in more than one merge request. 1. Backend, behind the `wip` feature flag `ai_flow_trigger_status_on_finish`. The flag is off for customers. 1. A follow-up merge request adds both fields to the trigger form (Automate, Triggers), behind the same flag. The fields appear next to the status filter for "Status changed". This merge request also adds the user documentation. 1. Rollout starts only after the UI exists and after these dependencies are met: - `ai_flow_trigger_chaining` is rolled out (https://gitlab.com/gitlab-org/gitlab/-/work_items/630476). - https://gitlab.com/gitlab-org/gitlab/-/merge_requests/261053 is merged. It lets a `work_item` status trigger start Duo Developer. Customers cannot use the feature until step 2 is merged. ## Why - A project can chain Generate Workplan, Duo Developer and Duo Code Review through statuses that the project chooses. The flows stay unchanged. - Each stage needs no hand-off flow, no extra CI job, and no extra level of chain depth. - The status names live in the trigger configuration, not in a prompt or a goal template. ## Evidence Measured on a GDK on 2026-10-09 with a local implementation of this proposal: - One human status change to `Planning` ran this chain: Generate Workplan, `Ready for development`, Duo Developer, a Draft merge request, `In review`. GitLab shows the service account of the flow that finished as the actor of each status change. - With `ai_flow_trigger_chaining` on, the Duo Developer session had the Generate Workplan session as its parent, with `trigger_source` set to `flow`. - A Generate Workplan session that asked a question stayed `input_required`. The status changed only after a human answered and the session finished. - A stopped session changed nothing. - With `ready_merge_requests_on_finish`, the merge request of Duo Developer left Draft, and Duo Code Review posted its review. ## Limits - A session can finish without doing the work. For example, Duo Developer can decide that a work item needs no code change and open no merge request. The status still moves. To keep the status, a flow that stops early must end as failed or as waiting for input. The documentation must say this. - The settings apply to sessions that run on a work item. A session that runs on a merge request changes no status. ## Dependencies - The Duo Developer stage needs https://gitlab.com/gitlab-org/gitlab/-/merge_requests/261053, which lets a `work_item` status trigger start Duo Developer. - The chain needs `ai_flow_trigger_chaining` (https://gitlab.com/gitlab-org/gitlab/-/work_items/630476) or `allow_flow_originated_cloud_event_triggers` to be on. Both are off by default. ## Acceptance - [ ] The table `ai_flow_triggers` has `status_on_finish` and `ready_merge_requests_on_finish`, with validation. - [ ] GraphQL create, update, and read support both fields, marked as experiments. The feature flag gates the behaviour. - [ ] When a triggered session finishes, its work item moves to `status_on_finish`. The write runs as the composite identity of the session. - [ ] Nothing changes when the session did not finish. Nothing changes when the work item left the trigger status. - [ ] With `ready_merge_requests_on_finish`, the Draft merge requests that the session created leave Draft. - [ ] The status-changed event carries the composite actor and the workflow of the session, so that chaining records the parent. - [ ] The documentation for both settings, the flags that the chain depends on, and the limits comes with the UI change. - [ ] The trigger form shows both settings for "Status changed" triggers.