## This issue duplicates much of the work outlined [here](https://gitlab.com/gitlab-org/gitlab/-/work_items/598578). Merge Tooling functionality will be broken out separately. Content of this work item may change. ## Goal Provide a clear in product experience to reconcile multiple Top-level groups (from multiple organizations) into a single organization and dissolve the redundant empty organizations, while explaining the purpose of organizations and how the reconciliation affects features like Artifact Registry. This tooling supports the managed bulk transfer and on demand paths described in ADR 008 and relies on the future friendly namespace approach for Artifact Registry so that Organization merges do not require disruptive data migrations. ## Outcome Organization owners can reconcile multiple TLGs into a single Organization intentionally, using a guided merge flow that communicates impact to billing, Artifact Registry boundaries, permissions, workflows, namespaces, owners, hierarchies of groups and projects, and users. Merges are modeled as a two party operation, where a source TLG owner or Organization owner initiates the merge and a destination Organization owner explicitly accepts it before execution. After merge, the source Organization is effectively dissolved and the destination Organization becomes the single boundary for the merged TLGs and their inherited configuration, while users experience minimal disruption. ## Workflow 1. **\[Removed. This is part of Merge Tooling.\] ~~Start from the destination Organization.~~**\~\~ An authorized destination Organization owner opens the destination Organization landing page and sees other customer owned Organizations and their eligible TLGs that can be consolidated into this Organization.\~\~\~\~ 2. **Initiate the move from source to destination.** The owner selects a TLG and moves it into the destination Organization through a guided reconciliation action. The intended model is customer led and centered on moving a source TLG into an existing destination Organization rather than auto combining Organizations in the background. 3. **Validate permission and technical constraints before execution.** The flow confirms that only authorized owners can perform the action and blocks moves that violate technical or licensing constraints, with understandable error messaging when the move cannot proceed. 4. **\[Removed. This is part of Merge Tooling.\] ~~Require explicit two party approval before merge execution.~~** ~~The merge is treated as a two party operation where a source TLG owner or source Organization owner initiates the merge and a destination Organization owner explicitly accepts it before the system proceeds.~~ 5. **Re anchor the TLG and apply Organization scoped effects.** Once approved, the system updates the TLG to the destination `org_id`. Organization scoped capabilities, including Artifact Registry and related Organization anchored features, now treat the destination Organization as the new boundary for that TLG and its inherited configuration. 6. **Remove the TLG from the source Organization and dissolve the source if empty.** After the move, the TLG no longer appears under the source Organization. If the source Organization no longer owns any TLGs, it is automatically dissolved and removed from navigation and Organization lists. 7. **The owner can track progress in a Merge status screen.** This includes success, partial success with warnings, or failure states. 8. **Finish with a clear success state and minimal user disruption.** The experience should communicate the resulting impacts to billing, permissions, workflows, namespaces, owners, group and project hierarchy, users, and Artifact Registry boundaries, while keeping customer disruption low. ## Aggregated definition of done * A complete, guided merge experience exists from Organization overview through to successful merge and dissolution of unnecessary Organizations. * Merge tooling is aligned with Organization data migration and Artifact Registry architecture so that merges are forward compatible with Cells and namespace based storage. * Internal and external documentation explains merge behavior, limitations, and best practices. ## Aggregated success metrics * Number of Organizations with multiple TLGs after launch, compared to before launch, in target customer segments. * Reduction in manual merges and back office interventions for Organization consolidation. * Customer satisfaction with the clarity and safety of merge operations, based on surveys and customer interviews. * Absence of significant incidents involving data loss or prolonged unavailability tied to merge operations. <!-- STATUS NOTE START --> ## Status 2026-06-18 :clock1: **total hours spent this week by all contributors**: ~32 (estimate; no time-tracking entries recorded this period) :tada: **achievements**: - Merged and deployed to production the organization confirmation service https://gitlab.com/gitlab-org/gitlab/-/merge_requests/238706+ — the backend service that flips an organization to `confirmed` and triggers the top-level group transfer. This was in final review last week and is now live. - Advanced the organization-confirmed event https://gitlab.com/gitlab-org/gitlab/-/work_items/598469+ into review; this emits the event that downstream services subscribe to in order to create organization users on confirmation. - Scoped and opened the frontend work to wire the reconciliation UI to the backend https://gitlab.com/gitlab-org/gitlab/-/work_items/603249+, connecting the completed flow end-to-end. :issue-blocked: **blockers**: - The frontend "call transfer and confirm API" work https://gitlab.com/gitlab-org/gitlab/-/work_items/603249+ is blocked pending completion of the confirmation GraphQL API https://gitlab.com/gitlab-org/gitlab/-/work_items/596669+. :arrow_forward: **next**: - Complete review and merge of the organization-confirmed event https://gitlab.com/gitlab-org/gitlab/-/work_items/598469+. - Build the confirmation GraphQL API https://gitlab.com/gitlab-org/gitlab/-/work_items/596669+ to unblock the frontend. - Create `organization_users` records on confirmation https://gitlab.com/gitlab-org/gitlab/-/work_items/597856+. - Connect the reconciliation UI to the transfer/confirm API https://gitlab.com/gitlab-org/gitlab/-/work_items/603249+. _Copied from https://gitlab.com/groups/gitlab-org/-/epics/21394#note_3467357187_ <!-- STATUS NOTE END -->