info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/249160) in GitLab 13.7 for group resources [with a flag](../../feature_flags.md) named `bulk_import`. Disabled by default.
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267945) in GitLab 14.4 for project resources [with a flag](../../feature_flags.md) named `bulk_import_projects`. Disabled by default.
> - New application setting `bulk_import_enabled` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/383268) in GitLab 15.8. `bulk_import` feature flag removed.
On self-managed GitLab, by default [migrating group items](#migrated-group-items) is not available. To show the
feature, ask an administrator to [enable it in application settings](../../admin_area/settings/visibility_and_access_controls.md#enable-migration-of-groups-and-projects-by-direct-transfer).
Also on self-managed GitLab, by default [migrating project items](#migrated-project-items-beta) is not available. To show
- Copy groups with projects (in [beta](../../../policy/alpha-beta-support.md#beta-features) 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](../../../administration/feature_flags.md) named `bulk_import_projects`.
- The network connection between instances or GitLab.com must support HTTPS.
- Any firewalls must not block the connection between the source and destination GitLab instances.
- Both GitLab instances must have group migration by direct transfer
[enabled in application settings](../../admin_area/settings/visibility_and_access_controls.md#enable-migration-of-groups-and-projects-by-direct-transfer)
by an instance administrator.
- The source GitLab instance must be running GitLab 14.0 or later.
- You must have a [personal access token](../../../user/profile/personal_access_tokens.md) for the source GitLab
instance:
- For GitLab 15.1 and later source instances, the personal access token must have the `api` scope.
- For GitLab 15.0 and earlier source instances, the personal access token must have both the `api` and
`read_repository` scopes.
- 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](https://gitlab.com/gitlab-org/gitlab/-/issues/387891) in GitLab 15.8 and will be removed in
GitLab 16.0.
### Prepare user accounts
To ensure GitLab maps users and their contributions correctly:
1. Create the required users on the destination GitLab instance. When migrating to GitLab.com, you must create users
manually unless [SCIM](../../group/saml_sso/scim_setup.md) is used. Creating users with the API is only available to
self-managed instances because it requires administrator access.
1. Check that users have a public email on the source GitLab instance that matches their primary email on the
destination GitLab instance.
1. Ensure that users confirm their primary email addresses on the destination GitLab instance. Most users receive an
email asking them to confirm their email address.
1. If using an OmniAuth provider like SAML, link GitLab and SAML accounts of users on GitLab. All users on the
destination GitLab instance must sign in and verify their account on the destination GitLab instance. If using
[SAML SSO for GitLab.com groups](../../group/saml_sso/index.md), users must
[link their SAML identity to their GitLab.com account](../../group/saml_sso/index.md#linking-saml-to-your-existing-gitlabcom-account).
### Connect the source GitLab instance
Create the group you want to import to and connect the source GitLab instance:
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.
1. Next to the groups you want to import, select either:
- **Import with projects**. Importing groups with projects is in [Beta](../../../policy/alpha-beta-support.md#beta-features). 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.
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](https://gitlab.com/gitlab-org/gitlab/-/blob/14-10-stable-ee/lib/gitlab/import_export/group/import_export.yml).
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267945) in GitLab 14.4 [with a flag](../../feature_flags.md) named `bulk_import_projects`. Disabled by default.
> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/339941) in GitLab 15.6.
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](https://gitlab.com/gitlab-org/gitlab/-/blob/14-10-stable-ee/lib/gitlab/import_export/project/import_export.yml).
The [`import_export.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/import_export/group/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](https://gitlab.com/gitlab-org/gitlab/-/blob/14-10-stable-ee/lib/gitlab/import_export/group/import_export.yml).
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](https://gitlab.com/gitlab-org/gitlab/-/issues/291983) in GitLab 15.4)
- Events
- [Wikis](../../project/wiki/group.md)
([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53247) in GitLab 13.9)
- Iterations cadences ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95372) 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**.
1. On the left sidebar, select **Settings > General**.
1. Expand **Visibility and access controls**.
1. 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.
1. On the left sidebar, select **Settings > General**.
1. In the **Advanced** section, select **Export Group**.
1. After the export is generated, you should receive an email with a link to the [exported contents](#exported-contents)
in a compressed tar archive, with contents in NDJSON format.
1. Alternatively, you can download the export from the UI:
1. Return to your group's **Settings > General** page.
1. 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](../../../api/group_import_export.md).
### Import the group
1. Create a new group:
- On the top bar, select **Create new…** (**{plus-square}**) and then **New group**.
