- Import your groups into GitLab
- Automate group and project import
- Migrated group resources
- Migrated project resources
- Troubleshooting Group Migration
bulk_import. On self-managed GitLab, by default migrating project resources is not available. To show this feature, ask an administrator to enable the feature flag named
bulk_import_projects. On GitLab.com, migrating group resources is available but migrating project resources is not available.
Users with the Owner role on a top-level group can migrate it to:
- Another top-level group.
- The subgroup of any existing top-level group.
- Another GitLab instance, including GitLab.com.
Migrating groups using the method documented here is not the same as migrating groups using file exports. Importing and exporting groups using file exports requires you to export a group to a file and then import that file in another GitLab instance. Migrating groups using the method documented here automates this step.
When you migrate a group, you connect to your GitLab instance and then choose groups to import. Not all the data is migrated. See:
Leave feedback about group migration in the relevant issue.
Before you begin, ensure that the target GitLab instance can communicate with the source over HTTPS (HTTP is not supported). You might need to reconfigure your firewall to prevent blocking the connection on the self-managed instance.
Then create the group you want to import into, and connect:
Create a new group or subgroup:
- On the top bar, select
+and then New group.
- Or, on an existing group’s page, in the top right, select New subgroup.
- On the top bar, select
- Select Import group.
- Enter the source URL of your GitLab instance.
- Generate or copy a personal access token
read_repositoryscopes on your remote GitLab instance.
- Enter the personal access token for your remote GitLab instance.
- Select Connect instance.
After you have authorized access to the GitLab instance, you are redirected to the GitLab Group Migration importer page. The remote groups you have the Owner role for are listed.
- By default, the proposed group namespaces match the names as they exist in remote instance, but based on your permissions, you can choose to edit these names before you proceed to import any of them.
- Next to the groups you want to import, select Import.
- The Status column shows the import status of each group. If you leave the page open, it updates in real-time.
- After a group has been imported, select its GitLab path to open its GitLab URL.
For information on automating user, group, and project import API calls, see Automate group and project import.
Only the following resources are migrated to the target instance. Any other items are not migrated:
- Badges (Introduced in 13.11)
- Board Lists
- Epics (Introduced in 13.7)
- Group Labels (Introduced in 13.9)
- Iterations (Introduced in 13.10)
- Members (Introduced in 13.9)
Group members are associated with the imported group if:
- The user already exists in the target GitLab instance and
- The user has a public email in the source GitLab instance that matches a confirmed email in the target GitLab instance
- Milestones (Introduced in 13.10)
- Namespace Settings
- Milestones (Introduced in GitLab 15.0).
bulk_import_projects. On GitLab.com, migrating project resources are not available.
- Projects (Introduced in GitLab 14.4)
- Auto DevOps (Introduced in GitLab 14.6)
- Branches (including protected branches) (Introduced in GitLab 14.7)
- CI Pipelines (Introduced in GitLab 14.6)
- Designs (Introduced in GitLab 15.1)
- Issues (Introduced in GitLab 14.4)
- Labels (Introduced in GitLab 14.4)
- LFS Objects (Introduced in GitLab 14.8)
- Members (Introduced in GitLab 14.8)
- Merge Requests (Introduced in GitLab 14.5)
- Migrate Push Rules (Introduced in GitLab 14.6)
- Pull Requests (including external pull requests) (Introduced in GitLab 14.5)
- Pipeline History (Introduced in GitLab 14.6)
- Pipeline Schedules (Introduced in GitLab 14.8)
- Releases (Introduced in GitLab 15.1)
- Release Evidences (Introduced in GitLab 15.1)
- Repositories (Introduced in GitLab 14.4)
- Snippets (Introduced in GitLab 14.6)
- Uploads (Introduced in GitLab 14.5)
- Wikis (Introduced in GitLab 14.6)
In a rails console session, you can find the failure or error messages for the group import attempt using:
# Get relevant import records import = BulkImports::Entity.where(namespace_id: Group.id).map(&:bulk_import) # Alternative lookup by user import = BulkImport.where(user_id: User.find(...)).last # Get list of import entities. Each entity represents either a group or a project entities = import.entities # Get a list of entity failures entities.map(&:failures).flatten # Alternative failure lookup by status entities.where(status: [-1]).pluck(:destination_name, :destination_namespace, :status)
Introduced in GitLab 14.10.
When troubleshooting group migration, an import may not complete because the import workers took
longer than 8 hours to execute. In this case, the
status of either a
# Get relevant import records import = BulkImports::Entity.where(namespace_id: Group.id).map(&:bulk_import) import.status #=> 3 means that the import timed out.