doc/user/group/import/direct_transfer_migrations.md
{{< details >}}
{{< /details >}}
To migrate GitLab groups and projects by using direct transfer:
If there are any problems, you can:
{{< history >}}
{{< /history >}}
Before migrating by using direct transfer, see the following prerequisites.
/tmp directory
to create and extract archives of transferred projects and groups.To maximize the chance of a successful and performant migration:
If the source and destination instances are not the same version, the source instance must not be more than two minor versions earlier than the destination instance. This requirement does not apply for migrations from GitLab.com to GitLab Dedicated.
api scope.proxy_download.18.0 will become 18.0 (imported-3d-1770206299). To avoid this, rename the milestone in the source group or project before initiating a direct transfer.{{< history >}}
bulk_import_importer_user_mapping. Disabled by default.bulk_import_importer_user_mapping removed.{{< /history >}}
Users are never created during a migration. Instead, user memberships on the source instance are mapped to users on the destination instance. The type of mapping for user memberships depends on the membership type on the source instance:
In GitLab 18.4 and later, when you create direct memberships while importing a project directly into an existing group, the Users cannot be added to projects in this group setting is respected.
When mapping inherited and shared memberships, if the user has an existing membership in the destination namespace with a higher role than the one being mapped, the membership is mapped as a direct membership instead. This ensures the member does not get elevated permissions.
[!note] There is a known issue affecting the mapping of shared memberships.
To ensure GitLab maps users and their contributions correctly between the source and destination instances:
There is no way in the GitLab UI or API to automatically set public email addresses for users. If you need to set a lot of user accounts to have public email addresses, see issue 284495 for a potential workaround.
On the destination GitLab instance, create the group you want to import to and connect the source GitLab instance:
{{< history >}}
{{< /history >}}
After you have authorized access to the source GitLab instance, you are redirected to the GitLab group importer page. Here you can see a list of the top-level groups on the connected source instance where you have the Owner role.
If you do not want to import all user memberships from the source instance, ensure the Import user memberships checkbox is cleared. For example, the source instance might have 200 members, but you might want to import 50 members only. After the import completes, you can add more members to groups and projects.
{{< history >}}
bulk_import_details_page. Enabled by default.bulk_import_details_page removed in GitLab 16.8.{{< /history >}}
To review the results of an import:
You can also see that an item was imported when you see an Imported badge on some items in the GitLab UI.
{{< history >}}
{{< /history >}}
You can view all groups migrated by you by direct transfer listed on the group import history page. This list includes:
To view group import history:
If required, you can cancel a running migration by using either the REST API or a Rails console.
For information on canceling a running migration with the REST API, see cancel a migration.
To cancel a running migration with a Rails console:
Start a Rails console session on the destination GitLab instance.
Find the last import by running the following command. Replace USER_ID with the user ID of the user that started the import:
bulk_import = BulkImport.where(user_id: USER_ID).last
Cause the import and all items associated with it to fail by running the following command:
bulk_import.entities.each do |entity|
entity.trackers.each do |tracker|
tracker.batches.each(&:fail_op!)
end
entity.trackers.each(&:fail_op!)
entity.fail_op!
end
bulk_import.fail_op!
Canceling a bulk_import doesn't stop workers that are exporting the project on the source instance, but prevents the
destination instance from:
If your migrations fail, or partially succeed but are missing items, you can retry the migration. To retry a migration of a top-level group and all of its subgroups and projects, or specific subgroups or projects, use either the GitLab UI or the group and project migration by direct transfer API.