# Group Approval Step — Feature Proposal ## Overview This proposal introduces a new work item type and a corresponding flow step for GitLab's Duo Agent Platform: the **Group Approval**. It enables flow authors to insert a formal, multi-stakeholder review gate into a flow at any point where a consequential decision needs to be made before proceeding. The Group Approval is designed for moments where a single-user chat confirmation is insufficient — where a plan needs to be seen, debated, edited, and formally approved by multiple people before an AI continues acting on it. --- ## Problem Statement Current human-in-the-loop mechanisms for AI flows and agents are designed for single-user approval. This is appropriate for low-stakes or easily reversible actions. However, flows that touch production systems, affect many files or services, or require cross-functional buy-in need a higher-ceremony process. Beyond the tactical need for multi-party approval, there is a broader problem: **business decisions in most organizations are poorly captured.** Decisions happen in meetings, in Slack threads, or as comments buried in large issues. AI agents operating within an organization have no reliable way to access the reasoning behind past decisions. GitLab already serves as a system of record for code changes; it is well-positioned to become a system of record for the decisions that precede and justify those changes. --- ## Proposed Solution ### The Group Approval Work Item A new work item type — **Group Approval** — dedicated to capturing a structured proposal, facilitating discussion, and recording a formal decision. Functionally inspired by the merge request (reviewers, approvals, threaded comments, diff history) but applied to plans and decisions rather than code. When generated by a flow, a Group Approval is created automatically and the flow pauses until the item reaches a terminal state: **Approved**, **Declined**, or **Re-run Requested**. Group Approvals can also be created manually, independent of any flow, for teams that want to use them for general decision capture — RFCs, architectural decisions, proposals, and similar artifacts. ### The Group Approval Flow Step A configurable step type that flow authors can insert into any custom flow. When the flow reaches this step, it: 1. Generates a Group Approval work item populated with AI-generated content from the flow's gathered context 2. Notifies all required reviewers 3. Pauses the flow and waits for the approval outcome 4. Proceeds, cancels, or re-runs based on the outcome --- ## Work Item Structure ### Content - **Plain-language summary** — a short, non-technical description of what the flow is planning to do and why. Readable by any stakeholder regardless of technical background. - **Detailed plan** — the full AI-generated plan, structured as discrete elements (sections, steps, key decisions) to enable element-level diffing. - **Impact statement** — a one-sentence description of what cannot happen without this approval, surfaced prominently so reviewers can triage before reading deeply. - **Required context** — a checklist defined by the flow author of what reviewers should know or verify before deciding. - **Flow session link** — a curated summary of what happened in prior flow steps, with a link to the full session log. - **Linked work items** — references to issues, MRs, epics, or other work items that are part of the flow's context (e.g., the issue that triggered a Developer Flow, the MR tied to a pipeline fix). ### Diff and Edit History The plan is stored as structured content. Any reviewer can edit it. **Any edit clears all existing approvals**, requiring a full re-review cycle. The diff view shows changes at the element level (paragraph, heading, list item) rather than line by line, making meaningful changes legible regardless of prose formatting. Reviewers can see what changed since they last reviewed the item, supporting efficient re-review after edits. ### Review States Each required reviewer can set their status to: - **Approved** — satisfied with the plan as written - **Requested changes** — leaving comments but not blocking (informational) - **Declined** — voting to cancel the flow entirely ### Terminal States The work item resolves when one of the following conditions is met, as configured by the flow author: | State | Trigger | Flow Outcome | |---|---|---| | **Approved** | Required approver threshold met | Flow proceeds to next step | | **Declined** | Any required reviewer declines (or configurable threshold) | Flow is cancelled | | **Re-run Requested** | Any reviewer triggers a re-run | Flow restarts from step 1 with discussion as added context | | **Expired** | Timeout threshold reached | Configurable: expire and notify, or cancel | ### Re-run Behavior When a reviewer triggers a re-run, all comments and discussion on the Group Approval work item are packaged as context and passed to the new flow instance. This closes a feedback loop that most AI systems leave open — the review discussion becomes direct input to the next attempt, improving its odds of success. The original Group Approval is closed and linked to the new run for traceability. Note: re-runs currently restart from step 1 of the flow. A future improvement would allow flow authors to designate an earlier re-entry step, enabling more targeted retries when the problem was identified at a specific point in the flow. --- ## Flow Step Configuration When a flow author adds a Group Approval step, they configure: - **Required reviewers** — static list of users, a role (e.g., any Maintainer in this project), or both - **Approval threshold** — unanimous, or a minimum number of approvals required - **Decline behavior** — any decline cancels, or a threshold of declines required - **Timeout** — duration before expiry, and behavior on expiry (cancel or notify) - **Required context checklist** — items reviewers should verify before approving - **Plan format guidance** — optional instructions to the AI about how to structure the generated plan for this specific step --- ## Approval Tiers in Flows Flow authors should have two human-in-the-loop options, chosen based on the stakes of the action: | Type | Mechanism | Best For | |---|---|---| | **Single-user approval** | Inline chat interruption, low ceremony | Low-stakes, easily reversible, triggering user has full context | | **Group approval** | Group Approval work item, full review cycle | High blast radius, cross-functional input needed, formal record required | This keeps the Group Approval step reserved for moments where its friction is genuinely warranted and intentional. --- ## Integration with Existing GitLab Patterns This feature is designed to extend familiar GitLab patterns rather than introduce entirely new ones: - **Todos** — required reviewers receive a Todo item when a Group Approval is created, routing through a channel they already monitor - **Notifications** — standard GitLab notification settings apply - **Audit log** — all approvals, edits, and state changes are recorded as audit events - **Work item relationships** — Group Approvals link to parent issues, MRs, epics using existing relationship types - **Activity feed** — appears in project and group activity alongside other work items --- ## Relationship to the Knowledge Graph and AI Context A secondary but meaningful benefit: Group Approvals as a formal data type create a structured, queryable record of organizational decisions. As GitLab's Knowledge Graph and RAG capabilities mature, agents will be better positioned to retrieve and reason over past decisions — understanding not just what changed in the codebase, but why it was decided. This is not a primary justification for building the feature, but it is a compounding benefit over time. --- ## Open Questions - Should Group Approvals be available outside of flows as a standalone feature from day one, or scoped to flow-generated approvals initially? - Should the flow be able to dynamically add reviewers based on what it discovers during context gathering (e.g., auto-adding a security engineer if a sensitive file is in scope)? - What is the right home for Group Approvals in GitLab's navigation — alongside Issues and MRs, under Automate, or both? - How should Group Approvals interact with GitLab's existing Compliance features, particularly for organizations with regulated change management requirements? --- ## Related Features - GitLab Duo Agent Platform — Flows - Design Management (structural analog: versioned non-code artifact review) - Merge Request Approvals - Work Items - GitLab Duo Chat (single-user approval via chat interruption) --- --- # Group Approval Step — User Journeys --- ## Journey 1: Single-User Chat Approval ### Fixing a Failing Pipeline Test **Context:** Maya is a mid-level backend engineer. A CI pipeline on her feature branch has been failing for two hours. She opens the failed pipeline view and clicks **Fix with GitLab Duo**. --- **Step 1 — Flow begins** The Fix Pipeline Flow starts. Duo surfaces a message in the Chat panel: > *Analyzing pipeline failure in branch `feat/payment-retry`…* Maya minimizes the sidebar and keeps working on something else. --- **Step 2 — Context gathered** After about 30 seconds, Duo has read the job log, identified the failure, and traced it to a brittle integration test that is asserting against a hardcoded timestamp. --- **Step 3 — Single-user approval (inline chat)** The flow reaches its approval step. Because this is a low-impact fix scoped entirely to Maya's feature branch, the flow author configured a **single-user chat approval** rather than a group approval. Duo interrupts with a message in the Chat panel: > **Duo:** I've identified the issue. The test `spec/payments/retry_spec.rb:114` is asserting against a hardcoded Unix timestamp that expired. I'd like to replace it with a relative time helper. > > **Proposed change:** > - `expect(job.created_at).to eq(1691500800)` → `expect(job.created_at).to be_within(1.second).of(Time.current)` > > This only affects your feature branch. Should I go ahead? > > **[ Apply fix ] [ Show me the full diff ] [ Cancel ]** Maya glances at the proposed change, recognizes the pattern immediately, and clicks **Apply fix**. --- **Step 4 — Flow completes** Duo commits the change to her branch, triggers a new pipeline run, and posts a summary in chat. Total time from trigger to resolution: under two minutes. Maya never left her IDE context. --- --- ## Journey 2: Group Approval ### Migrating a Monolith's Authentication Layer to a New Identity Provider **Context:** Meridian Health is a healthcare technology company running a large GitLab Ultimate instance. Their platform team manages `meridian-core`, a Rails monolith that powers patient records, provider scheduling, and billing for 400 hospitals. Their current identity provider contract is expiring. The CTO has asked the platform team to scope and execute a migration to a new SSO provider within the quarter. A senior engineer, Priya, has built a custom flow — the **Identity Migration Flow** — to automate the heavy lifting. It has been tested against a staging environment. This is its first run against production configuration. Priya starts the flow from the `meridian-core` project. She is the triggering user. --- **Step 1 — Context gathering (automated)** The flow spends several minutes gathering context autonomously: - Reads the current Devise and OmniAuth configuration across the monolith - Enumerates all 34 services that authenticate against the current IdP via SAML or OAuth - Reads the current IdP's SCIM provisioning setup and maps it to active user groups - Pulls the open issue [#8821 — IdP Migration Q3](link) which contains the vendor decision thread and the chosen replacement provider - Reads three linked architecture decision records from the past year - Identifies 6 services with custom session handling that will require manual intervention - Scans for hardcoded IdP URLs across 12 repositories in the `meridian` group --- **Step 2 — Plan generated** The flow generates a migration plan. It is structured, detailed, and long. The flow reaches the **Group Approval step**. --- **Step 3 — Group Approval work item created** A new Group Approval work item is automatically created in the `meridian-core` project: **[GA-004] Identity Provider Migration — Execution Plan**. The flow is now paused. **Required reviewers** (as configured by Priya when building the flow): - `@daniel-r` — Staff Engineer, Platform - `@soo-kim` — Engineering Manager, Platform - `@rachel-t` — Director of Security & Compliance - `@ben-o` — VP of Engineering All four receive a **Todo** and an email notification. --- **What the work item surfaces:** > **Impact statement:** This flow will modify authentication configuration across 34 services and all active user sessions. If approved and executed incorrectly, all 400 hospital portals will be unable to authenticate users until manually rolled back. > **Summary (plain language):** The flow has mapped the full scope of the current identity provider integration and generated a phased migration plan. It proposes to update all SAML and OAuth configurations, migrate SCIM group mappings, update hardcoded URLs across 12 repositories, and generate feature-flagged rollout configuration so the migration can be activated per region. Six services with custom session handling are flagged for manual intervention — the flow will not touch these automatically. > **Required context checklist** (authored by Priya): > - [ ] Confirm the replacement IdP vendor contract has been signed > - [ ] Confirm staging migration completed successfully (see pipeline #44821) > - [ ] Confirm rollback procedure has been reviewed by on-call team > - [ ] Confirm change window has been scheduled and hospital IT liaisons notified > **Linked work items:** > - Issue #8821 — IdP Migration Q3 (triggering issue) > - MR !2201 — Staging migration results > - Architecture Decision Record: SSO Vendor Selection > **Flow session:** [View full session log →](#) Below the summary, the full structured plan is expanded in sections: Pre-migration validation, Configuration changes by service, SCIM group mapping updates, Repository URL patches, Feature flag rollout sequence, Rollback procedure. --- **Step 4 — Review and discussion** Over the next two days, the reviewers read the plan and discuss in threaded comments on the work item. `@daniel-r` reviews the technical detail first. He notices the plan proposes updating the billing service (`meridian-billing`) in Phase 1, but that service is in a code freeze until the end of the quarter. > **@daniel-r:** `meridian-billing` is in code freeze until Oct 31. We can't touch it in Phase 1. Can we move it to Phase 3, after the freeze lifts? I'm going to edit the plan to reflect this. Daniel edits the Phase 1 section of the plan, moving `meridian-billing` to Phase 3 and adjusting the dependency order. **All four existing approvals are cleared.** Everyone receives a notification that the plan has changed and their review is required again. `@rachel-t` reviews from a compliance angle. HIPAA audit logging requirements mean the migration must ensure zero gap in session audit trail continuity. She adds a comment: > **@rachel-t:** Audit log continuity during the SCIM migration window isn't addressed here. Before I approve, I need to see this handled explicitly in the plan. Adding a note — not editing the plan myself since this requires input from the flow on how it intends to handle it. Priya sees the comment. She re-runs the flow (triggering it from the work item's **Re-run** action) with a note: > *Re-running with feedback: address HIPAA audit log continuity during SCIM migration window. meridian-billing moved to Phase 3.* The flow restarts from step 1, ingesting the full comment thread and the edited plan as additional context. It returns 20 minutes later with a revised plan that adds an explicit audit log bridging step and respects the billing code freeze. A new Group Approval work item **[GA-005]** is created, linked back to GA-004 for traceability. --- **Step 5 — Second review cycle** The revised plan is reviewed. Rachel is satisfied with the audit log handling and approves. Daniel approves. Soo-Kim approves. Ben reviews the plain-language summary and impact statement — he doesn't read the full technical plan — and approves. All four required approvals are met. The work item status changes to **Approved** and is locked. --- **Step 6 — Flow resumes** The flow receives the approval signal and resumes from where it paused, now operating against the approved and human-edited plan. It begins executing Phase 1 changes under a feature flag in a maintenance window that was pre-scheduled. The Group Approval work item remains permanently in the project as a record of what was decided, who approved it, what was debated, and what was changed before the decision was finalized. Six months later, a new engineer on the platform team is trying to understand why `meridian-billing` has a different auth configuration than the other services. They find the answer in GA-004 and GA-005 without asking anyone.