<!-- triage-serverless v3 PLEASE DO NOT REMOVE THIS SECTION --> *This page may contain information related to upcoming products, features and functionality. It is important to note that the information presented is for informational purposes only, so please do not rely on the information for purchasing or planning purposes. Just like with all projects, the items mentioned on the page are subject to change or delay, and the development, release, and timing of any products, features, or functionality remain at the sole discretion of GitLab Inc.* <!-- triage-serverless v3 PLEASE DO NOT REMOVE THIS SECTION --> ## Parity with Group Export/Import  (Viable) ### Problem to Solve Users migrating GitLab Groups from one instance to another currently have two choices: 1. Using the [(Single) Group Export/Import](https://docs.gitlab.com/ee/user/group/settings/import_export.html) feature which requires a longer, two-step process (downloading and uploading a file), but contains all the related data (milestones, epics, labels, boards) 2. Using the [Group Migration](https://gitlab.com/groups/gitlab-org/-/epics/4374) feature, which is faster and easier to use, but only migrates the group without the related data - [Some users](https://gitlab.com/groups/gitlab-org/-/epics/4619#note_738548858) who operate in air-gapped environments to move groups (and projects) from one network to another (where there is no connectivity between them) can't use the group Migration, so the only way for them to migrate data is the file bases export/import approach. ### Additional info to consider ProServ use [Congregate](https://gitlab.com/gitlab-org/professional-services-automation/tools/migration/congregate), which leverages the group import/export API. ### User experience goal Users should be able to navigate to the Group Migration page, authenticate with another instance of GitLab and migrate an entire group with the subgroups and all the related data (except projects), via a single click. ### Proposal Iteratively add more related data to the Group Migration until we reach full parity with the existing [Group Export/Import](https://docs.gitlab.com/ee/user/group/settings/import_export.html) functionality. While Group Migration will be the main tool for migration, we will keep the old files based approach behind FF to support use cases that the group migration doesn't support - offline networks between GitLab instances. Once Group migration contains all related data similar to export/import, we will hide the import/export behind FF, so most users will use the group migration, and users with air-gapped networks and ProServ will continue to use the import/export. 1. Add all of the Epic fields to the migration - https://gitlab.com/groups/gitlab-org/-/epics/5189 1. Migrate [Group Milestones](https://docs.gitlab.com/ee/user/project/milestones/#milestones) and Events with the Group - https://gitlab.com/gitlab-org/gitlab/-/issues/292427 1. Migrate [Iterations](https://docs.gitlab.com/ee/user/group/iterations/) with the Group - https://gitlab.com/gitlab-org/gitlab/-/issues/292428 1. Migrate [Group Labels](https://docs.gitlab.com/ee/user/project/labels.html) with the Group - ~~https://gitlab.com/gitlab-org/gitlab/-/issues/292429~~ https://gitlab.com/gitlab-org/gitlab/-/issues/297460 1. Migrate [Boards](https://docs.gitlab.com/ee/user/project/issue_board.html) and Boards Lists with the Group - https://gitlab.com/gitlab-org/gitlab/-/issues/292430 1. Migrate [Badges](https://docs.gitlab.com/ee/user/project/badges.html#project-badges) with the Group - https://gitlab.com/gitlab-org/gitlab/-/issues/292431 1. Provide an API for Group Migration - https://gitlab.com/gitlab-org/gitlab/-/issues/301109 ### Out of Scope The following items will not be migrated: 1. Runner tokens 1. SAML discovery tokens ### Documentation * [x] The documentation delivered in [this doc issue](https://gitlab.com/gitlab-org/gitlab/-/issues/292107) should be updated with the details of this epic's implementation. * [x] The [Beta badge and warning message](https://gitlab.com/gitlab-org/gitlab/-/issues/290231) should be removed from the Group Import page, as the feature is now **Viable**. - https://gitlab.com/gitlab-org/gitlab/-/issues/338983 * [x] [Enable Group Migration](https://docs.gitlab.com/ee/user/group/import/#enable-or-disable-gitlab-group-migration) feature ([flag](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/feature_flags/development/bulk_import.yml)) by default - https://gitlab.com/gitlab-org/gitlab/-/issues/338985 * [x] Document Group Export/Import [deprecation](https://gitlab.com/gitlab-org/gitlab/-/issues/332957) ([comments below](https://gitlab.com/groups/gitlab-org/-/epics/4619#note_624985184)) * [x] Document the “hybrid” mode: the ability to use Group migration for groups and Project export/import for projects. - https://gitlab.com/gitlab-org/gitlab/-/issues/338983 * [x] Record a demo of Group migration (with Project export/import) - https://youtu.be/iNXnO_NP1E4 * [x] ~~Create a blog about Group migration~~ - This will make more sense after projects are added to migration. * [x] [Announce](https://gitlab.com/gitlab-org/gitlab/-/issues/331469#note_591556890) in #customer-success ### Deprecation With the delivery of [Parity with Group Export/Import](https://gitlab.com/groups/gitlab-org/-/epics/4619) this feature would become Viable  and become a replacement for the [Group Export/Import](https://docs.gitlab.com/ee/user/group/settings/import_export.html) functionality for migrating Groups. The Group Export/Import feature can be deprecated at this point. Proposed deprecation schedule: * `14.4` announce deprecation of Group Exports as of `14.6` ~documentation https://gitlab.com/gitlab-org/gitlab/-/issues/332957+ * `14.6` hide Group Exports behind a feature flag ~frontend https://gitlab.com/gitlab-org/gitlab/-/issues/341282+ * `14.6` announce deprecation of Group Imports as of `14.8` ~documentation * `14.8` hide Group Imports behind a feature flag ~frontend https://gitlab.com/gitlab-org/gitlab/-/issues/341275+ * `14.8` hide Group Export/Import API behind a feature flag ~backend * `15.0` ~~remove feature flags, any and all code and documentation related to Group Export/Import~~ ~backend ~frontend ~documentation * '15.3' Update the documentation that import/export functionality is behind a Feature Flag. ### Release notes The new [GitLab Migration](https://docs.gitlab.com/ee/user/group/import/) feature can now migrate an entire Group with all the Subgroups and related data. The data migrated includes all the everything contained in Group Exports, making this a much easier way to migrate entire Groups.  Documentation: https://docs.gitlab.com/ee/user/group/import/