Migrating by direct transfer is generally available

Migrating GitLab groups and projects by direct transfer is now generally available from GitLab 18.3. This brings an easy-to-use and automated way of migrating GitLab resources between GitLab instances to an even broader audience.

Using direct transfer enables you to easily create a copy of chosen GitLab resources on the same or another GitLab instance. You can use either the UI or API. The UI is intuitive and straightforward, while the API gives you additional flexibility in terms of choosing resources to be copied.

Migrating by direct transfer is a major improvement from migrating groups and projects using file exports because of the following:

• You don't need to manually export each individual group and project to a file and then import all those export files to a new location. Now, you can directly migrate any top-level group you have the Owner role for with all its sub-groups and projects.
• It allows for post-import user contribution mapping (such as issue or comment authorship), which gives you greater flexibility and control.
• It works reliably with large projects. Thanks to resource batching and concurrent execution of import and export processes the chance of interruption or timeout is significantly lowered.
• It offers better insights into the migration while it runs as well as after it completes. In the UI you can observe as the numbers grow as more items are imported. Then you can review the results. You can see that an item was imported thanks to an Imported badge on items in the GitLab UI.

We’ve come a long way since GitLab 14.3 when we started supporting the direct migration of the group resources. In GitLab 15.8, we extended this functionality to projects as a beta. Since then, we have worked to improve the efficiency and reliability of importing, especially for large projects. We thoroughly reviewed the feature from a security and instance stability standpoint.

To give an example of the sizes of the groups and projects we've tested with, and their import duration, we've seen successful imports of:

• 100 projects (19.9k issues, 83k merge requests, 100k+ pipelines) that migrated in 8 hours
• 1,926 projects (22k issues, 160k merge requests, 1.1 million pipelines) that migrated in 34 hours

On GitLab.com, migrating by direct transfer is enabled by default. On GitLab Self-Managed and on GitLab Dedicated, an administrator must enable the feature in application settings.

When to use migrating by direct transfer and how to get the best results

Migrating by direct transfer requires network connection between instances or GitLab.com. Therefore, customers that use air-gapped networks with no connectivity between their GitLab instances still have to use file exports to copy their GitLab data. They will be able to use migrating groups and projects by direct transfer after we extend this solution to also support offline instances.

Before you attempt a migration, review documentation, including prerequisites, group items, and project items that are migrated. Some items are excluded from migration or not yet supported.

Migrate between most recent possible versions

We recommend migrating between versions that are as recent as possible. Update the source and destination instances to take advantage of all improvements and bug fixes we’ve added over time.

Prepare for user contribution mapping post migration

Familiarize yourself with user contribution and membership mapping process so you know what to expect after migration completes and what are the next steps for you to take.

Review options to reduce migration duration

Depending on where you’re migrating to, GitLab.com, a self-managed instance, or Dedicated, you can employ various strategies to reduce the migration duration.

How can I review the results?

You can view all groups and projects migrated by you by direct transfer listed on the group import history page. For each group and project, you can view statistics for imported items and dig down into details in case some items were not imported. Alternatively, you can use API endpoints to do the same.

In cases where most of your projects completed successfully but one or two end up missing some relations, like merge requests or issues, we recommend that you try re-importing those projects by using the API.

What’s next for migrating by direct transfer?

We are excited to bring migration by direct transfer to general availability and hope you are too! We want to hear from you. What's the most important missing piece for you? What else can we improve? Let us know in the migration by direct transfer feedback issue and we'll keep iterating!