Migrating GitLab groups

You can migrate GitLab groups:

  • From self-managed GitLab to GitLab.com.
  • From GitLab.com to self-managed GitLab.
  • From one self-managed GitLab instance to another.
  • Between groups in the same GitLab instance.

You can migrate groups in two ways:

  • By direct transfer (recommended).
  • By uploading an export file.

If you migrate from GitLab.com to self-managed GitLab, an administrator can create users on the self-managed GitLab instance.

Version history
On self-managed GitLab, by default migrating group items is not available. To show the feature, ask an administrator to enable it in application settings. Also on self-managed GitLab, by default migrating project items is not available. To show this feature, ask an administrator to enable the feature flag named bulk_import_projects. The feature is not ready for production use. On GitLab.com, migration of both groups and projects is available.

Migrating groups by direct transfer copies the groups from one place to another. You can:

  • Copy many groups at once.
  • Copy top-level groups to:
    • Another top-level group.
    • The subgroup of any existing top-level group.
    • Another GitLab instance, including GitLab.com.
  • Copy groups with projects (in beta and not ready for production use) or without projects. Copying projects with groups is available:
    • On GitLab.com by default.
    • On self-managed GitLab instances after an administrator first enables the feature flag named bulk_import_projects.

Not all group and project resources are copied. See list of copied resources below:

We invite you to leave your feedback about migrating by direct transfer in the feedback issue.

If you want to move groups instead of copying groups, you can transfer groups if the groups are in the same GitLab instance. Transferring groups is a faster and more complete option.

Prerequisites

To migrate groups by direct transfer:

  • The network connection between instances or GitLab.com must support HTTPS.
  • Both GitLab instances must have group migration by direct transfer enabled in application settings by an instance administrator.
  • You must have the Owner role on the source group to migrate from.
  • You must have at least the Maintainer role on the destination group to migrate to. Using the Developer role for this purpose was deprecated in GitLab 15.8 and will be removed in GitLab 16.0.

Visibility rules

After migration:

  • Private groups and projects stay private.
  • Public groups and projects:
    • Stay public when copied into a public group.
    • Become private when copied into a private group.

If used a private network on your source instance to hide content from the general public, make sure to have a similar setup on the destination instance, or to import into a private group.

Preparation

GitLab maps users and their contributions correctly provided:

  • Users already exist on the target GitLab instance.
  • Users have a public email on the source GitLab instance that matches their primary email on the target GitLab instance.
  • Users’ primary email addresses on the target GitLab instance are confirmed. Most users receive an email asking them to confirm their email address.
  • When using an OmniAuth provider like SAML, GitLab and SAML accounts of users on GitLab must be linked. All users on the target GitLab instance must sign in and verify their account on the target GitLab instance.

You might need to reconfigure your firewall to prevent blocking the connection on the self-managed instance.

If you use SAML SSO for GitLab.com groups, contributing users must have linked their SAML identity to their GitLab.com account.

When migrating to GitLab.com, you must create users manually unless SCIM is used. Creating users with the API is only available to self-managed instances because it requires administrator access.

Connect to the source GitLab instance

Create the group you want to import to and connect the source:

  1. Create either:
    • A new group. On the top bar, select , then New group, and select Import group.
    • A new subgroup. On existing group’s page, either:
      • Select New subgroup.
      • On the top bar, Select and then New subgroup. Then on the left sidebar, select the import an existing group link.
  2. Enter the URL of your source GitLab instance.
  3. Generate or copy a personal access token on your source GitLab instance with:
    • The api scope, if the source GitLab instance on version 15.1 or later.
    • Both api and read_repository scopes, if the source GitLab instance on version 15.0 or earlier.
  4. Enter the personal access token for your source GitLab instance.
  5. Select Connect instance.

Select the groups to import

Introduced in GitLab 15.8, option to import groups with or without projects.

After you have authorized access to the source GitLab instance, you are redirected to the GitLab group importer page. The top-level groups on the connected source instance you have the Owner role for are listed.

  1. By default, the proposed group namespaces match the names as they exist in source 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 either:
    • Import with projects. Importing groups with projects is in Beta. This feature is not ready for production use.
    • Import without projects.
    • Import on self-managed GitLab, when the bulk_import_projects feature flag is disabled and the feature is not available.
  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 import history

You can view all groups migrated by you by direct transfer listed on the group import history page. This list includes:

  • Paths of source groups.
  • Paths of destination groups.
  • Start date of each import.
  • Status of each import.
  • Error details if any errors occurred.

To view group import history:

  1. Sign in to GitLab.
  2. On the top bar, select Create new… ().
  3. Select New group.
  4. Select Import group.
  5. Select History in the upper right corner.
  6. If there are any errors for a particular import, you can see them by selecting Details.

Migrated group items

The import_export.yml file for groups lists many of the items imported when migrating groups by direct transfer. View this file in the branch for your version of GitLab to see the list of items relevant to you. For example, import_export.yml on the 14-10-stable-ee branch.

Group items that are migrated to the target instance include:

  • Badges (Introduced in 13.11)
  • Board Lists
  • Boards
  • Epics (Introduced in 13.7)
    • Epic resource state events (Introduced in GitLab 15.4)
  • Finisher
  • Group Labels (Introduced in 13.9)
  • Iterations (Introduced in 13.10)
  • Iterations cadences (Introduced in 15.4)
  • 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
  • Releases
  • Subgroups
  • Uploads

Any other items are not migrated.

Migrated project items (beta)

Version history
On self-managed GitLab, migrating project resources when migrating groups is not available by default. To make it available ask an administrator to enable the feature flag named bulk_import_projects. On GitLab.com, groups are migrated with all their projects by default.

The import_export.yml file for projects lists many of the items imported when migrating projects using group migration. View this file in the branch for your version of GitLab to see the list of items relevant to you. For example, import_export.yml on the 14-10-stable-ee branch.

caution
Migrating projects when migrating groups by direct transfer is in Beta and is not ready for production use.

Project items that are migrated to the target instance include:

Items excluded from migration, because they contain sensitive information:

  • Pipeline Triggers.

Troubleshooting

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)

You can also see all migrated entities with any failures related to them using an API endpoint.

Stale imports

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 BulkImport or BulkImport::Entity is 3 (timeout): 

# Get relevant import records
import = BulkImports::Entity.where(namespace_id: Group.id).map(&:bulk_import)

import.status #=> 3 means that the import timed out.

Error: 404 Group Not Found

If you attempt to import a group that has a path comprised of only numbers (for example, 5000), GitLab attempts to find the group by ID instead of the path. This causes a 404 Group Not Found error in GitLab 15.4 and earlier.

To solve this, you must change the source group path to include a non-numerical character using either:

  • The GitLab UI:

    1. On the top bar, select Main menu > Groups and find your group.
    2. On the left sidebar, select Settings > General.
    3. Expand Advanced.
    4. Under Change group URL, change the group URL to include non-numeric characters.

  • The Groups API.

Migrate groups by uploading an export file (deprecated)

Version history
  • Introduced in GitLab 13.0 as an experimental feature. May change in future releases.
  • Deprecated in GitLab 14.6.
caution
This feature was deprecated in GitLab 14.6 and replaced by migrating groups by direct transfer. To follow progress on a solution for offline environments, see the relevant epic.

Prerequisites:

  • Owner role on the group to migrate.

Using file exports, you can:

  • Export any group to a file and upload that file to another GitLab instance or to another location on the same instance.
  • Use either the GitLab UI or the API.
  • Migrate groups one by one, then export and import each project for the groups one by one.

GitLab maps user contributions correctly when an admin access token is used to perform the import. GitLab does not map user contributions correctly when you are importing from a self-managed instance to GitLab.com. Correct mapping of user contributions when importing from a self-managed instance to GitLab.com can be preserved with paid involvement of Professional Services team.

Note the following:

  • Exports are stored in a temporary directory and are deleted every 24 hours by a specific worker.
  • To preserve group-level relationships from imported projects, export and import groups first so that projects can be imported into the desired group structure.
  • Imported groups are given a private visibility level, unless imported into a parent group.
  • If imported into a parent group, a subgroup inherits the same level of visibility unless otherwise restricted.
  • You can export groups from the Community Edition to the Enterprise Edition and vice versa. The Enterprise Edition retains some group data that isn’t part of the Community Edition. If you’re exporting a group from the Enterprise Edition to the Community Edition, you may lose this data. For more information, see downgrading from EE to CE.

Compatibility

Group file exports are in NDJSON format. GitLab previously produced group file exports in JSON format, however:

  • From GitLab 15.8, GitLab no longer supports importing a JSON-formatted group file export.
  • Between GitLab 14.0 and GitLab 14.7, GitLab no longer produces group file exports in JSON format but, to support transitions, can still import JSON-formatted group file exports.

From GitLab 13.0, GitLab can import group file exports that were exported from a version of GitLab up to two minor versions behind, which is similar to our process for security releases.

For example:

Destination version Compatible source versions
13.0 13.0, 12.10, 12.9
13.1 13.1, 13.0, 12.10

Exported contents

The import_export.yml file for groups lists items exported and imported when migrating groups using file exports. View this file in the branch for your version of GitLab to see the list of items relevant to you. For example, import_export.yml on the 14-10-stable-ee branch.

Group items that are exported include:

  • Milestones
  • Labels
  • Boards and Board Lists
  • Badges
  • Subgroups (including all the aforementioned data)
  • Epics
    • Epic resource state events (Introduced in GitLab 15.4)
  • Events
  • Wikis (Introduced in GitLab 13.9)
  • Iterations cadences (Introduced in 15.4)

Items that are not exported include:

  • Projects
  • Runner tokens
  • SAML discovery tokens

Preparation

  • To preserve the member list and their respective permissions on imported groups, review the users in these groups. Make sure these users exist before importing the desired groups.
  • Users must set a public email in the source GitLab instance that matches one of their verified emails in the target GitLab instance.

Enable export for a group

Prerequisite:

  • You must have the Owner role for the group.

To enable import and export for a group:

  1. On the top bar, select Main menu > Admin.
  2. On the left sidebar, select Settings > General.
  3. Expand Visibility and access controls.
  4. In the Import sources section, select the checkboxes for the sources you want.

Export a group

Prerequisites:

  • You must have the Owner role for the group.

To export the contents of a group:

  1. On the top bar, select Main menu > Groups and find your group.
  2. On the left sidebar, select Settings > General.
  3. In the Advanced section, select Export Group.
  4. After the export is generated, you should receive an email with a link to the exported contents in a compressed tar archive, with contents in NDJSON format.

  5. Alternatively, you can download the export from the UI:

    1. Return to your group’s Settings > General page.
    2. In the Advanced section, select Download export. You can also generate a new file by selecting Regenerate export.

You can also export a group using the API.

Import the group

  1. Create a new group:
    • On the top bar, select Create new… () and then New group.
    • On an existing group’s page, select New subgroup.
  2. Select Import group.
  3. Enter your group name.
  4. Accept or modify the associated group URL.
  5. Select Choose file.
  6. Select the file that you exported in the Export a group section.
  7. To begin importing, select Import group.

Your newly imported group page appears after the operation completes.

note
The maximum import file size can be set by the administrator, default is 0 (unlimited). As an administrator, you can modify the maximum import file size. To do so, use the max_import_size option in the Application settings API or the Admin Area. Default modified from 50 MB to 0 in GitLab 13.8.

Rate limits

To help avoid abuse, by default, users are rate limited to:

Request Type Limit
Export 6 groups per minute
Download export 1 download per group per minute
Import 6 groups per minute

Automate group and project import

For information on automating user, group, and project import API calls, see Automate group and project import.