Import and migrate groups and projects
Offering: GitLab.com, Self-managed, GitLab Dedicated
To bring existing projects to GitLab, or copy GitLab groups and projects to a different location, you can:
- Migrate GitLab groups and projects by using direct transfer.
- Import from supported import sources.
- Import from other import sources.
Migrate from GitLab to GitLab by using direct transfer
The best way to copy GitLab groups and projects between GitLab instances, or in the same GitLab instance, is by using direct transfer.
Another option is to move GitLab groups using group transfer.
You can also copy GitLab projects by using a GitLab file export, which is a supported import source.
Supported import sources
- All importers default to disabled for GitLab self-managed installations. This change was introduced in GitLab 16.0.
The import sources that are available to you by default depend on which GitLab you use:
- GitLab.com: all available import sources are enabled by default.
- GitLab self-managed: no import sources are enabled by default and must be enabled.
GitLab can import projects from these supported import sources.
Import source | Description |
---|---|
Bitbucket Cloud | Using Bitbucket.org as an OmniAuth provider, import Bitbucket repositories. |
Bitbucket Server | Import repositories from Bitbucket Server (also known as Stash). |
FogBugz | Import FogBugz projects. |
Gitea | Import Gitea projects. |
GitHub | Import from either GitHub.com or GitHub Enterprise. |
GitLab export | Migrate projects one by one by using a GitLab export file. |
Manifest file | Upload a manifest file. |
Repository by URL | Provide a Git repository URL to create a new project from. |
Disable unused import sources
Only import projects from sources you trust. If you import a project from an untrusted source,
an attacker could steal your sensitive data. For example, an imported project
with a malicious .gitlab-ci.yml
file could allow an attacker to exfiltrate group CI/CD variables.
GitLab self-managed administrators can reduce their attack surface by disabling import sources they don’t need:
- On the left sidebar, at the bottom, select Admin Area.
- Select Settings > General.
- Expand Visibility and access controls.
- Scroll to Import sources.
- Clear checkboxes for importers that are not required.
Other import sources
You can also read information on importing from these other import sources:
- ClearCase
- Concurrent Versions System (CVS)
- Jira (issues only)
- Perforce Helix
- Team Foundation Version Control (TFVC)
Import repositories from Subversion
GitLab can not automatically migrate Subversion repositories to Git. Converting Subversion repositories to Git can be difficult, but several tools exist including:
-
git svn
, for very small and basic repositories. -
reposurgeon
, for larger and more complex repositories.
View project import history
You can view all project imports created by you. This list includes the following:
- Paths of source projects if projects were imported from external systems, or import method if GitLab projects were migrated.
- Paths of destination projects.
- Start date of each import.
- Status of each import.
- Error details if any errors occurred.
To view project import history:
- Sign in to GitLab.
- On the left sidebar, at the top, select Create new () and New project/repository.
- Select Import project.
- In the upper-right corner, select the History link.
- If there are any errors for a particular import, select Details to see them.
The history also includes projects created from built-in or custom templates. GitLab uses import repository by URL to create a new project from a template.
Importing projects with LFS objects
When importing a project that contains LFS objects, if the project has an .lfsconfig
file with a URL host (lfs.url
) different from the repository URL host, LFS files are not downloaded.
Migrate by engaging Professional Services
If you prefer, you can engage GitLab Professional Services to migrate groups and projects to GitLab instead of doing it yourself. For more information, see the Professional Services Full Catalog.
Troubleshooting
Imported repository is missing branches
If an imported repository does not contain all branches of the source repository:
- Set the environment variable
IMPORT_DEBUG=true
. - Retry the import with a different group, subgroup, or project name.
- If some branches are still missing, inspect
importer.log
(for example, withjq
).