## Introduction This is the overall epic for Direct transfer feature. Direct transfer allows users to migrate in bulk GitLab groups and projects from one instance of GitLab to another via a single click. If you have any **feedback** regarding the tool, please comment on this [feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/284495 "Feedback issue for migrating groups and projects by direct transfer"). ## Historical context and current status of the feature Since version 14.3, GitLab has supported migrating GitLab groups by direct transfer, where, rather than manually uploading export files, data is transferred directly from the source instance to the target instance. In GitLab 15.8 we included the ability to migrate projects by direct transfer as a Beta. This beta feature is available to everyone, enabled by default on GitLab.com and with some configuration on self-managed GitLab instances. We've achieve General Availability for direct transfer in GitLab 18.3 ([epic](https://gitlab.com/groups/gitlab-org/-/epics/11398 "Direct Transfer General Availability")). You can read more about the benefits of the method and how to use it in<span dir=""> </span>the blog posts: * [GitLab project migration and automation - a perfect pair for faster, easier transfers](https://about.gitlab.com/blog/2023/01/18/try-out-new-way-to-migrate-projects/) * [How to migrate GitLab groups and projects more efficiently](https://about.gitlab.com/blog/2023/08/02/how-to-migrate-gitlab-groups-and-projects-more-efficiently/) * [Migrating by direct transfer is generally available](https://about.gitlab.com/blog/migrating-by-direct-transfer-is-generally-available/) or directly check the tool's [documentation](https://docs.gitlab.com/user/group/import/). ## Final user experience goal A one-stop-shop for migrating all or parts of your GitLab instance. Select an entire Group or just one Project and start a one-click migration. The user would not have to download or upload files. ## Proposed Solution To deliver this new solution, we will follow this iterative plan: 1. Group Migration MVC - https://gitlab.com/groups/gitlab-org/-/epics/4374 (done) 2. Parity with Group Export/Import - https://gitlab.com/groups/gitlab-org/-/epics/4619 (done) 3. Add Project metadata to Group Migration - https://gitlab.com/groups/gitlab-org/-/epics/4618 (done) 4. Add Project repositories to Group Migration - https://gitlab.com/groups/gitlab-org/-/epics/4615 (done) 6. World-class user experience - https://gitlab.com/groups/gitlab-org/-/epics/4617 (in progress) ### Requirements * Scalability and support for large migrations * Large groups and projects should migrate successfully * Resilience * Auto-retry for failed imports * Wait and retry when the connection is broken, or the other API is refusing requests (throttle) * Replayability * Redo import should be possible to retry items that were missed * Should be able to stop and restart the import * Efficiency * Fast * Not resource intensive (CPU, memory, disk space) * Transparency * Provide status while running * Accurately report success/failure/partial success * Provide a list of items that failed to import, so that the user can follow up * Usability * Ease of use * Discoverability * Ability to import into an existing project ## Impact on existing functionality With the delivery of [Parity with Group Export/Import](https://gitlab.com/groups/gitlab-org/-/epics/4619 "Group Migration - Parity with Group Export/Import") this feature became Viable  and is a superior replacement for the [Group Export/Import](https://docs.gitlab.com/ee/user/group/settings/import_export.html) functionality for migrating Groups. Completing this feature  created a superior replacement for [Project Export/Import](https://docs.gitlab.com/ee/user/project/settings/import_export.html) for migrating Projects from one instance to another. We have reached those milestones, but before we can evaluate the need to keep Group and Project Export/Imports as options for data migration in ~"Category:Importers", direct transfer needs to be able to support migrations between offline instances. We also aim to substitute the part of Congregate tool used by GitLab Professional Services which is about migrations of groups and projects between GitLab instances: https://gitlab.com/gitlab-org/gitlab/-/issues/378606+. ## Links * Reference list of all objects that need to be migrated: [Congregate GitLab migration features matrix](https://gitlab.com/gitlab-com/customer-success/professional-services-group/global-practice-development/migration/congregate/-/blob/master/gitlab-migration-features-matrix.md) ## Documentation * :book: [Contributor documentation](https://docs.gitlab.com/ee/development/bulk_import.html) * :book: [User documentation](https://docs.gitlab.com/ee/user/group/import/)