info:To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
---
# Migrating projects to a GitLab instance
1.[From Bitbucket Cloud](bitbucket.md)
1.[From Bitbucket Server (also known as Stash)](bitbucket_server.md)
1.[From ClearCase](clearcase.md)
1.[From CVS](cvs.md)
1.[From FogBugz](fogbugz.md)
1.[From GitHub.com or GitHub Enterprise](github.md)
1.[From GitLab.com](gitlab_com.md)
1.[From Gitea](gitea.md)
1.[From Perforce](perforce.md)
1.[From SVN](svn.md)
1.[From TFVC](tfvc.md)
1.[From repository by URL](repo_by_url.md)
1.[By uploading a manifest file (AOSP)](manifest.md)
1.[From Phabricator](phabricator.md)
1.[From Jira (issues only)](jira.md)
In addition to the specific migration documentation above, you can import any
Git repository via HTTP from the New Project page. Be aware that if the
repository is too large the import can timeout.
There is also the option of [connecting your external repository to get CI/CD benefits](../../../ci/ci_cd_for_external_repos/index.md). **(PREMIUM)**
# Migrate projects to a GitLab instance
See these documents to migrate to GitLab:
-[From Bitbucket Cloud](bitbucket.md)
-[From Bitbucket Server (also known as Stash)](bitbucket_server.md)
-[From ClearCase](clearcase.md)
-[From CVS](cvs.md)
-[From FogBugz](fogbugz.md)
-[From GitHub.com or GitHub Enterprise](github.md)
-[From GitLab.com](gitlab_com.md)
-[From Gitea](gitea.md)
-[From Perforce](perforce.md)
-[From SVN](svn.md)
-[From TFVC](tfvc.md)
-[From repository by URL](repo_by_url.md)
-[By uploading a manifest file (AOSP)](manifest.md)
-[From Phabricator](phabricator.md)
-[From Jira (issues only)](jira.md)
You can also import any Git repository through HTTP from the **New Project** page. Note that if the
repository is too large, the import can timeout.
You can also [connect your external repository to get CI/CD benefits](../../../ci/ci_cd_for_external_repos/index.md). **(PREMIUM)**
## LFS authentication
When importing a project that contains LFS objects, if the project has an [`.lfsconfig`](https://github.com/git-lfs/git-lfs/blob/master/docs/man/git-lfs-config.5.ronn)
file with a URL host (`lfs.url`) different from the repository URL host, LFS files are not downloaded.
## Migrating from self-managed GitLab to GitLab.com
## Migrate from self-managed GitLab to GitLab.com
If you only need to migrate Git repositories, you can [import each project by URL](repo_by_url.md). Issues and merge requests can't be imported.
If you want to retain all metadata like issues and merge requests, you can 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) will be changed to the user importing the project. For more information, please see [the import notes](../settings/import_export.md#important-notes).
If you need to migrate all data over, you can leverage our [API](../../../api/README.md) to migrate from self-managed to GitLab.com.
The order of assets to migrate from a self-managed instance to GitLab.com is the following:
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
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
information, see [the import notes](../settings/import_export.md#important-notes).
NOTE:
When migrating to GitLab.com, users would need to be manually created unless [SCIM](../../../user/group/saml_sso/scim_setup.md) is going to be used. Creating users with the API is limited to self-managed instances as it requires administrator access.
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 migrate all data from self-managed to GitLab.com, you can leverage the [API](../../../api/README.md).
Migrate the assets in this order:
1.[Groups](../../../api/groups.md)
1.[Projects](../../../api/projects.md)
...
...
@@ -55,43 +58,43 @@ When migrating to GitLab.com, users would need to be manually created unless [SC
Keep in mind the limitations of the [import/export feature](../settings/import_export.md#exported-contents).
You will still need to migrate your Container Registry over a series of
Docker pulls and pushes and re-run any CI pipelines to retrieve any build artifacts.
You must still migrate your [Container Registry](../../packages/container_registry/)
over a series of Docker pulls and pushes. Re-run any CI pipelines to retrieve any build artifacts.
## Migrating from GitLab.com to self-managed GitLab
## Migrate from GitLab.com to self-managed GitLab
The process is essentially the same as for [migrating from self-managed GitLab to GitLab.com](#migrating-from-self-managed-gitlab-to-gitlabcom). The main difference is that users can be created on the self-managed GitLab instance by an administrator through the UI or the [users API](../../../api/users.md#user-creation).
The process is essentially the same as [migrating from self-managed GitLab to GitLab.com](#migrate-from-self-managed-gitlab-to-gitlabcom).
The main difference is that an administrator can create users on the self-managed GitLab instance
through the UI or the [users API](../../../api/users.md#user-creation).
## Migrating between two self-managed GitLab instances
## Migrate between two self-managed GitLab instances
The best method for migrating from one GitLab instance to another,
perhaps from an old server to a new server for example, is to
[back up the instance](../../../raketasks/backup_restore.md),
then restore it on the new server.
To migrate from an existing self-managed GitLab instance to a new self-managed GitLab instance, it's
best to [back up](../../../raketasks/backup_restore.md)
the existing instance and restore it on the new instance. For example, this is useful when migrating
a self-managed instance from an old server to a new server.
In the event of merging two GitLab instances together (for example, both instances have existing data on them and one can't be wiped),
refer to the instructions in [Migrating from self-managed GitLab to GitLab.com](#migrating-from-self-managed-gitlab-to-gitlabcom).
To instead merge two self-managed GitLab instances together, use the instructions in
[Migrate from self-managed GitLab to GitLab.com](#migrate-from-self-managed-gitlab-to-gitlabcom).
This method is useful when both self-managed instances have existing data that must be preserved.
Additionally, you can migrate users using the [Users API](../../../api/users.md) with an administrator user.
Also note that administrators can use the [Users API](../../../api/users.md)
to migrate users.
## Project aliases **(PREMIUM SELF)**
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3264) in GitLab Premium 12.1.
When migrating repositories to GitLab and they are being accessed by other systems,
it's very useful to be able to access them using the same name especially when
they are a lot. It reduces the risk of changing significant number of Git URLs in
a large number of systems.
GitLab provides a functionality to help with this. In GitLab, repositories are
usually accessed with a namespace and project name. It is also possible to access
them via a project alias. This feature is only available on Git over SSH.
GitLab repositories are usually accessed with a namespace and a project name. When migrating
frequently accessed repositories to GitLab, however, you can use project aliases to access those
repositories with the original name. Accessing repositories through a project alias reduces the risk
associated with migrating such repositories.
A project alias can be only created via API and only by GitLab administrators.
Follow the [Project Aliases API documentation](../../../api/project_aliases.md) for
more details.
This feature is only available on Git over SSH. Also, only GitLab administrators can create project
aliases, and they can only do so through the API. For more information, see the
[Project Aliases API documentation](../../../api/project_aliases.md).
After an alias has been created for a project (such as an alias `gitlab` for the
project `https://gitlab.com/gitlab-org/gitlab`), you can clone the repository
with the alias (e.g `git clone git@gitlab.com:gitlab.git` instead of
