@@ -61,20 +61,43 @@ file with a URL host (`lfs.url`) different from the repository URL host, LFS fil
## Migrate from self-managed GitLab to GitLab.com
Depending on your requirements, there are several ways to migrate from self-managed GitLab to GitLab.com.
### Migrate using GitLab Migration (recommended)
Using [GitLab Migration](../../group/import/index.md), you can migrate top-level groups you are the Owner of, with all their subgroups and projects included.
GitLab Migration maps users and their contributions correctly on GitLab.com provided:
- Contributing users exist on GitLab.com at the time of the import.
- Those users have a public email on the source GitLab instance that matches their primary email on GitLab.com.
If you use [SAML SSO for GitLab.com groups](../../group/saml_sso/index.md),
contributing users must have [linked their SAML identity to their GitLab.com account](../../group/saml_sso/index.md#linking-saml-to-your-existing-gitlabcom-account).
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.
### Migrate specific projects only
If you only need to migrate Git repositories, you can [import each project by URL](repo_by_url.md).
However, you can't import issues and merge requests this way. To retain all metadata like issues and
However, you can't import issues and merge requests this way. To retain metadata like issues and
merge requests, use the [import/export feature](../settings/import_export.md)
to export projects from self-managed GitLab and import those projects into GitLab.com. All GitLab
user associations (such as comment author) are changed to the user importing the project. For more
to export projects from self-managed GitLab and import those projects into GitLab.com.
GitLab maps user contributions correctly when an admin access token is used to perform the import.
As a result, the import/export feature does not map user contributions correctly when you are importing projects from a self-managed instance to GitLab.com.
Instead, all GitLab user associations (such as comment author) are changed to the user importing the project. For more
information, see the prerequisites and important notes in these sections:
-[Export a project and its data](../settings/import_export.md#export-a-project-and-its-data).
-[Import the project](../settings/import_export.md#import-a-project-and-its-data).
NOTE:
When migrating to GitLab.com, you must create users manually unless [SCIM](../../../user/group/saml_sso/scim_setup.md)
will be used. Creating users with the API is limited to self-managed instances as it requires
administrator access.
To preserve contribution history, [migrate using GitLab Migration](#migrate-using-gitlab-migration-recommended).
### Migrate using the API
To migrate all data from self-managed to GitLab.com, you can leverage the [API](../../../api/index.md).
Migrate the assets in this order:
...
...
@@ -83,7 +106,7 @@ Migrate the assets in this order:
Keep in mind the limitations of the [import/export feature](../settings/import_export.md#items-that-are-exported).
Keep in mind the limitations of the [import/export feature](../settings/import_export.md#items-that-are-exported). As with [Migrating specific projects using the import/export feature](#migrate-specific-projects-only) user associations (such as comment author) are changed to the user importing projects when migrating from self-managed to GitLab.com.
You must still migrate your [Container Registry](../../packages/container_registry/index.md)
over a series of Docker pulls and pushes. Re-run any CI pipelines to retrieve any build artifacts.
