## Problem Today, when someone mentions `@GitLab` in Slack, the session runs and bills in **that person's own default GitLab Duo group**. Everyone in the same Slack workspace ends up somewhere different: different group, different settings, different credits. The result is "it works for me but not for you", and no administrator has a single place to set it up or see what is going on. Where the Slack app was installed has no influence on this. `AppMentionedService` picks any installation of the workspace, and the session then runs in `current_user.default_duo_namespace.root_ancestor`. ## Proposal **One Slack workspace, one GitLab Duo group.** An Owner of a top-level group picks it once, normally just by installing the app on that group. Every GitLab Duo session from that Slack workspace then runs and bills in that group, for everyone. Notifications and slash commands keep working exactly as today. Only _where a Duo session runs_ changes. - Design discussion, proof of concept and a 3-minute video: https://gitlab.com/groups/gitlab-org/-/work_items/23704#note_4003608381 - Proof of concept, do not merge (includes a seed script to click through every state locally): https://gitlab.com/gitlab-org/gitlab/-/merge_requests/261784 (closed, replaced by https://gitlab.com/gitlab-org/gitlab/-/merge_requests/262856) ## Goal for 19.6 **Every GitLab Duo session from a Slack workspace runs and bills in one top-level group, chosen by an Owner of that group, or by the administrator on self-managed.** Everything else in this issue supports that goal. ## What users see | Who | What changes | |-----|--------------| | Owner of a top-level group | Installs the app on the group, GitLab Duo is on, no second step. The integration page shows status and a **Fix** button when something is off | | Project Maintainer | Keeps full control of notifications and slash commands. Sees where GitLab Duo runs and who to ask | | Administrator (self-managed) | Picks the group in the Admin area | | Person in Slack, workspace not set up | A reply with a link, saying who can turn it on | | Person in Slack, workspace set up | Unchanged, except that the session now runs in the group the Owner chose | ## Decisions | Topic | Decision | |-------|----------| | Unit | One Duo group per Slack workspace (`team_id`), always a top-level group. No row means GitLab Duo in Slack is off for that workspace | | Who chooses | Owner of the top-level group. Administrator for instance-wide installs | | Group install | Claims the workspace automatically and turns on the Slack flow there | | Project install | Does not claim. Notifications and slash commands only. The project's top-level group is suggested to its Owners. New installs are steered to top-level groups, because a group install already gives every project below it a copy for slash commands and per-project notification settings. Project installs stay for Maintainers without an Owner, personal namespaces, and projects on a different Slack workspace than their group | | Instance-wide install | Off until the administrator picks a group | | Existing workspaces | Off until someone chooses. No auto-pick and no fallback to the user's default namespace. The GitLab Duo part of the Slack app is experimental, so this is acceptable | | Second group tries to claim | Rejected, with "managed in another group". The group is named only if the viewer can see it | | Moving Duo to another group | Needs an Owner of both groups. Not in 19.6 | | Turning Duo off | Affects new sessions only. Running sessions finish under their start settings | | Cross-group work | Delegated sessions, for example GitLab Duo Developer, bill where the target project lives, as in GitLab Duo Chat | | Slack flow | A Duo group always runs the Slack API flow. The Developer flow is no longer used for Slack. `slack_duo_api_flow` still decides whether that flow is available | | Self-managed | Default on in 19.6, admin picker included | | Notifications | The GitLab Duo section ships first, above the existing notification settings, which stay unchanged. The collapsed notifications block from Nick's design is a separate, optional MR that ships once Nick and Kamil agree on how to present notifications next to the newer app. Not on the critical path, see https://gitlab.com/groups/gitlab-org/-/work_items/23704#note_4005590222 | | Several workspaces in one group | Supported by the backend. Whether the group page shows the "Other Slack workspaces in this group" block is still open with Nick (https://gitlab.com/groups/gitlab-org/-/work_items/23704#note_4031872475). It is a UI switch in split MR 6, so it does not block the backend MRs | | Cells | Sharding key `duo_namespace_id`, the Duo group. The Cells claim for `team_id` (https://gitlab.com/gitlab-org/gitlab/-/work_items/633611) lands before any code writes rows, so it blocks MR 3. Event routing by `team_id` comes later with the Slack workspace entity (https://gitlab.com/gitlab-org/gitlab/-/work_items/636530) | ## Technical design Where this section and the reference MR differ, the reference MR (https://gitlab.com/gitlab-org/gitlab/-/merge_requests/262856) is the source of truth, except for the changes listed here: the feature flag actor and the boundary between split MRs 2 and 4. ### Data New table `slack_workspaces`: | Column | Notes | |--------|-------| | `team_id` | Slack workspace ID, unique across organizations | | `duo_namespace_id` | The Duo group, top-level group only, and the sharding key. Foreign key to `namespaces` with cascade delete | - Named after the workspace, not the Duo group, because the bot token and scopes move into this table later (the Slack workspace entity, https://gitlab.com/gitlab-org/gitlab/-/work_items/636530). - **Sharding key `duo_namespace_id`**, decided in database review (https://gitlab.com/gitlab-org/gitlab/-/merge_requests/263649#note_4100379399). An `organization_id` copy was added first and then removed: every row belongs to one top-level group, so the namespace is the most specific key and follows the group on transfers. The sharding key is immutable, so **changing a workspace's Duo group deletes the row and creates a new one**. The reference `ChangeDuoGroupService` already does that (Disable, then Enable, in one transaction); keep it that way and never `update` `duo_namespace_id`. - The unique index on `team_id` is **global**, because one Slack workspace has exactly one Duo group; an index scoped to `duo_namespace_id` would enforce nothing. It stays next to the Cells claim, like `jira_connect_installations.forge_installation_xid`. The claim (https://gitlab.com/gitlab-org/gitlab/-/work_items/633611) lands before any code writes rows, agreed in https://gitlab.com/gitlab-org/gitlab/-/merge_requests/263649#note_4101077185. Deliberately **not** a field on `integrations`: group and instance integrations are copied down to every project by `PropagateIntegrationWorker`, which is the opposite of "one place". ### Status contract The backend computes, the frontend renders. One payload per integration page and viewer: - `state`: `not_connected`, `off`, `on_here`, `elsewhere`, `instance_managed` - `checks`: `{ id, ok, fix }`, only for people who can manage - `can_manage`, `duo_group` (only when visible), `action_path`, `admin_path` Layout and copy changes then stay frontend-only. ### Feature flag `slack_duo_group`, type `wip` for now. The flag definition and `Workspace.duo_group_feature_enabled?` ship with MR 3, not with the table. It switches to `beta` before it is enabled by default, tracked in https://gitlab.com/gitlab-org/gitlab/-/work_items/633582. Off means today's behaviour, on means the new behaviour with no fallback. Actor: the top-level group. - Group and project pages, services: the page's top-level group. - Mention path: the Duo group of a claimed workspace. An unclaimed workspace has no group yet and checks `:instance`. Checking "any top-level group the workspace is installed in" would read every install of the workspace on each mention (2.1 s cold for GitLab's own workspace), the same read the "not set up" reply dropped. While the flag is on for some groups only, an unclaimed workspace keeps today's default-namespace path, and a mention that releases a stale claim moves its workspace back to that path. Implemented in https://gitlab.com/gitlab-org/gitlab/-/merge_requests/266172. - Admin area and the install page picker have no group and check `:instance`. The group actor lets us turn it on for one group on GitLab.com first (dogfooding) instead of switching off GitLab Duo in Slack for every unclaimed workspace at once. ### API style REST, consistent with the rest of the integrations edit page, which posts to `propsSource.formPath` and receives its props from HAML. ## Merge requests **Reference MR (full end-to-end build, not merged as is):** https://gitlab.com/gitlab-org/gitlab/-/merge_requests/262856, branch `duo/slack-duo-group-v2`. It is the design and behavior to align with and gets split into the MRs below, so the work can be distributed across the team. Take files from that branch rather than rewriting them. Its description has the setup steps, screenshots, decisions and follow-ups, and the test-world seed is in https://gitlab.com/gitlab-org/gitlab/-/merge_requests/262856#note_4029700315. The v1 stack (https://gitlab.com/gitlab-org/gitlab/-/merge_requests/261830, https://gitlab.com/gitlab-org/gitlab/-/merge_requests/261845, https://gitlab.com/gitlab-org/gitlab/-/merge_requests/262156 to https://gitlab.com/gitlab-org/gitlab/-/merge_requests/262161, https://gitlab.com/gitlab-org/gitlab/-/merge_requests/262165, https://gitlab.com/gitlab-org/gitlab/-/merge_requests/262171) is closed and replaced by it. Each split MR stays inert while `slack_duo_group` is off. MRs not yet opened have no link. | \# | MR | Scope | Depends on | Reviews | |----|----|-------|------------|---------| | 1 | **Merged:** data (https://gitlab.com/gitlab-org/gitlab/-/merge_requests/263649) | `slack_workspaces` table sharded by `duo_namespace_id`, `Integrations::SlackWorkspace::Workspace` model, factory, dev fixture, `db/docs` and data retention, foreign key handling for `Groups::DestroyService`. No callers, no queries | – | database | | 2 | **Merged:** building blocks (https://gitlab.com/gitlab-org/gitlab/-/merge_requests/263653) | `requires_enablement` attribute and validation on foundational flows (no flow sets it yet), `DuoRequirements`, `DuoGroupReplies` (Slack reply texts) | – | backend, technical writing | | 3 | **In review:** eligibility, turn on and off (https://gitlab.com/gitlab-org/gitlab/-/merge_requests/265962). `DisableDuoGroupService` moved to MR 5, which calls it | **Started from branch `duo/feature/633566-duo-group-eligibility`**, which already carries `DuoGroupEligibility`, the new `SlackIntegration` scopes, the `slack_duo_group` flag definition, `Workspace.duo_group_feature_enabled?(group)` and the `keela_excluded.yml` entries. Add on top: Enable, Disable and Release services, `update_duo_in_slack` ability, audit events `duo_in_slack_enabled` and `duo_in_slack_disabled`, claim on the first top-level install. **Owes the EXPLAIN plans for the three scopes** (see "Database review"). **Rebase first:** the parked branch still carries the old table, model and spec with `organization_id`; take MR 1's versions of those files | 1, Cells claim (https://gitlab.com/gitlab-org/gitlab/-/work_items/633611) | database, backend, authorization | | 4 | **In review:** mention path (https://gitlab.com/gitlab-org/gitlab/-/merge_requests/266172), stacked on MR 3 | `DuoMentionResolver`, `AppMentionedService` and Slack adapter wiring, `block_slack_duo_mention` event. Also `requires_enablement: false` for `slack_assistant/v1`, the skip in `SyncFoundationalFlowsService` and the flow settings filter, all gated by the flag | 2, 3 | backend, analytics | | 5 | Group page backend | `DisableDuoGroupService` (moved from MR 3), group endpoints and routes, `DuoWorkspacesPresenter`, `DuoGroupReference`, integration helpers | 3 | backend | | 6 | Group and project UI | GitLab Duo section, requirements card, copy, workspace list. The "Other Slack workspaces in this group" block sits behind a switch until the layout is decided | 5 | frontend, UX | | 7 | Admin area, full stack | Admin endpoint, `ChangeDuoGroupService`, admin overview and picker (self-managed) | 3, components from 6 | backend, frontend | | 8 | Install page, full stack | Profile controller and helper, install page picker and search (`install_target_dropdown.vue`) | 3 | frontend, backend | | 9 | Docs | User docs, development page, audit event docs | the behavior it documents | technical writing | | N | Optional, not blocking: replace the notification settings with the collapsed block from Nick's design. Ships when Nick and Kamil agree | – | – | frontend, UX | 1 and 2 are merged. 3 and 4 are in review, and 4 is stacked on 3. 3 is on the critical path: everything except 9 waits on it. 3 also waits on the Cells claim for `team_id` (https://gitlab.com/gitlab-org/gitlab/-/work_items/633611), which needs a Topology Service MR first, so start that in parallel with 3. Once 3 is in, 4, 5, 7 and 8 can go to different people. Why the Slack flow switch is in 4 and not in 2: `SyncFoundationalFlowsService` skips flows with `requires_enablement: false` without checking the flag, so shipping it in 2 would change behavior with the flag off. ### Decided while splitting These differ from the reference MR. Later split MRs follow them. - **Each MR ships only code that has a caller.** The table ships alone; everything else travels with the MR that calls it. That is why `DuoGroupEligibility`, the `SlackIntegration` scopes and the flag moved out of MR 1 and into MR 3 (https://gitlab.com/gitlab-org/gitlab/-/merge_requests/263649#note_4088440329). - **The order stays layer-first, not feature-first.** A vertical slice (table plus mention path in one MR) was proposed in review and turned down for this feature: the migration plus a database maintainer is the longest lead time, so the table goes first and review runs while the rest is built, and MR 2 already merged on this shape. Worth revisiting for the next feature. - **"Not set up" reply stays generic.** A mention in a workspace without a Duo group says "An Owner of the top-level group that installed the app can turn it on", or points to the Admin area for instance installs. It no longer names the one group, because finding it read every install of the workspace (2.1 s cold for GitLab's own workspace). Can come back later. - **Eligibility uses EXISTS.** `DuoGroupEligibility` checks one group with two EXISTS queries instead of loading every top-level namespace of the workspace. Pages that load many workspaces still preload `root_namespace_ids_by_team`. - **No "Installed in" list** on the settings pages, and no reinstall link for workspaces connected lower in the hierarchy. The reinstall action stays for the page's own workspace and, through the Admin area, for instance workspaces. - **The Admin area lists only instance workspaces**, not every workspace that groups installed. What this means for the later MRs: | MR | Change against the reference | |----|------------------------------| | 4 Mention path | `DuoMentionResolver`: drop `single_root_group` and the `setup_by: 'owner'` context. `DuoGroupReplies` has no `owner` branch (removed in MR 2) | | 5 Group page backend | `DuoWorkspacesPresenter`: drop `places`, `places_in_hierarchy`, `root_places`, `PLACE_LIMIT` and `other_team_ids` (`excluding_teams`). `installed_in` is empty, or `[{ kind: :instance }]` for instance rows. `reinstall_path` only for the page's own workspace and instance workspaces | | 6, 7 UI | `slack_duo_workspace_list.vue`: hide "Installed in" when the list is empty | | 7 Admin area | `ChangeDuoGroupService`: keep Disable plus Enable in one transaction. `duo_namespace_id` is the sharding key and must not be updated in place | | 3–8 | Remove the matching entries from `scripts/lint/keela_excluded.yml` once a method gets its caller | ### Database review Settled in MR 1's review: 1. **Sharding key `duo_namespace_id`**, not `organization_id`: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/263649#note_4100379399 1. **Global unique index on `team_id`** stays, and the Cells claim lands before the first writer (MR 3): https://gitlab.com/gitlab-org/gitlab/-/merge_requests/263649#note_4101077185 1. **Cascade-only delete** of `slack_workspaces.duo_namespace_id`, listed in `spec/support/database/destroy_service_foreign_keys_todo.yml`, approved. **EXPLAIN plans:** MR 1 has no queries left, so it needs none. The three `SlackIntegration` scopes on the MR 3 branch do. The plans were run on postgres.ai for the earlier revision of MR 1 and were lost when that description was rewritten; the scope code is unchanged, so they only need re-running, not redesigning. ## Not in 19.6 - Moving GitLab Duo between groups. - Asking older installs to approve the newer Slack permissions. - Cells: routing Slack events by `team_id` and the Slack workspace entity: https://gitlab.com/gitlab-org/gitlab/-/work_items/636530. The `team_id` claim itself is in 19.6, see https://gitlab.com/gitlab-org/gitlab/-/work_items/633611. - Organization-level settings, once organizations have integration settings. ## Related - https://gitlab.com/gitlab-org/gitlab/-/work_items/632568 — who can use GitLab Duo in Slack - https://gitlab.com/gitlab-org/gitlab/-/work_items/632567 — clear error messages in Slack - https://gitlab.com/gitlab-org/gitlab/-/work_items/628439 — the Slack flow and its feature flag - https://gitlab.com/gitlab-org/gitlab/-/work_items/633582 — feature flag rollout - https://gitlab.com/gitlab-org/gitlab/-/work_items/633611 — Cells: claim `team_id`, blocks MR 3 - https://gitlab.com/gitlab-org/gitlab/-/work_items/636530 — Slack workspace entity: event routing and bot token