Migrate groups from another instance of GitLab

Version history
note
The importer migrates only the group data listed on this page. To leave feedback on this feature, see this issue.

Using GitLab Group Migration, you can migrate existing top-level groups from GitLab.com or a self-managed instance. Groups can be migrated to a target instance, as a top-level group, or as a subgroup of any existing top-level group.

The following resources are migrated to the target instance:

Any other items are not migrated.

Enable or disable GitLab Group Migration

GitLab Migration is deployed behind a feature flag that is enabled by default. GitLab administrators with access to the GitLab Rails console can enable it.

To enable it:

Feature.enable(:bulk_import)

To disable it:

Feature.disable(:bulk_import)

Import your groups into GitLab

Before you begin, ensure that the target instance of GitLab can communicate with the source over HTTPS (HTTP is not supported).

note
This might involve reconfiguring your firewall to prevent blocking connection on the side of self-managed instance.

Connect to the remote GitLab instance

  1. Go to the New Group page:

    • On the top bar, select + and then New group.
    • Or, on an existing group’s page, in the top right, select New subgroup.

    Navigation paths to create a new group

  2. On the New Group page, select Import group.

    Fill in import details

  3. Enter the source URL of your GitLab instance.
  4. Generate or copy a personal access token with the api and read_repository scopes on your remote GitLab instance.
  5. Enter the personal access token for your remote GitLab instance.
  6. Select Connect instance.

Selecting which groups to import

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.

  1. 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.
  2. Next to the groups you want to import, select Import.
  3. The Status column shows the import status of each group. If you leave the page open, it updates in real-time.
  4. After a group has been imported, select its GitLab path to open its GitLab URL.

Group Importer page