The following page may contain information related to upcoming products, features and functionality. It is important to note that the information presented is for informational purposes only, so please do not rely on the information for purchasing or planning purposes. Just like with all projects, the items mentioned on the page are subject to change or delay, and the development, release, and timing of any products, features or functionality remain at the sole discretion of GitLab Inc.
| Stage | Foundations |
| Maturity | N/A |
| Content Last Reviewed | 2024-04-17 |
Thanks for visiting this category direction page on Importers in GitLab. This page belongs to the Import and Integrate group of the Foundations stage and is maintained by the group's Product Manager, Magdalena Frankiewicz (E-mail, Calendly).
This direction page is a work in progress, and everyone can contribute:
A typical organization looking to adopt GitLab already has many other tools. Artifacts such as code, issues and epics may already exist and are being used daily. Seamless transition of work in progress is critically important and a great experience during this migration creates a positive first impression of GitLab. Solving these transitions, even for the complex cases, is crucial for GitLab’s ability to expand in the market. Instilling the confidence in the user that their data will be migrated quickly and with maximum care is of utmost importance.
Supporting the GitLab-hosted first product theme, the Import and Integrate group is working towards making imports reliable and performant at any scale. Large-scale moves to GitLab should be significantly easier and ultimately reach the first-class level experience.
Areas of interest and improvement can be organized by the following goals:
Ease of use Customers looking to import their data sometimes struggle to find the place in GitLab where they can initiate imports. Once found, the user interactions are not always intuitive and the flow is not fully user-friendly. Improving the user experience in this area will make our importers more lovable.
Reliability A portion of our current issues are related to the reliability of the solution. Imports don't always succeed and when they fail, there is little guidance for the user on steps they can take to remedy the failure. We are working on making our importers more reliable, so that our customers can have confidence in the migration process.
Scalability and performance Large organizations looking to move possibly hundreds or thousands of projects from tools like GitHub or Bitbucket to GitLab or from self-managed GitLab instance to GitLab.com or GitLab Dedicated need to be able to do so in a performant way.
At this time, GitLab is targeting the following high-level areas for import: GitLab self-managed to GitLab.com and GitLab Dedicated, source control tools, planning tools and CI/CD tools.
The Import and Integration group is focused on migrating groups and projects from one GitLab instance to another and from other software development tools like GitHub or Bitbucket.
Jenkins Importer is owned by the Verify:Pipeline Authoring group.
We're currently evaluating Jira importer.
Since version 14.3, GitLab has supported migrating GitLab groups by direct transfer, where, rather than manually uploading export files, data is transferred directly from the source instance to the target instance. In GitLab 15.8 we included the ability to migrate projects by direct transfer as a Beta. Although it's still in Beta, customers have been using this tool successfully in Production and we recommend importing by direct transfer over importing with file exports.
You can read more about the benefits of the method and how to use it in blog posts:
or directly check the tool's documentation.
Import by direct transfer is available to everyone, enabled by default on GitLab.com and with some configuration on self-managed GitLab instances.
Overall work on direct transfer can be tracked in gitlab&2771.
In 2024 we aim to:
If you have any feedback regarding the tool, please comment on this feedback issue.
What about migrating projects using file exports?
Because migrating by direct transfer requires network connection between instances or GitLab.com, customers that are using air-gapped networks with no network connectivity between their GitLab instances have to still use file exports to copy their GitLab data. They will be able to use migrating groups and projects by direct transfer after we extend this solution to also support offline instances.
Another goal within Importers category in 2024 is to implement a Jira importer to provide a built-in way to adopt GitLab's planning features. We're evaluating an existing MVC solution (docs and epic) and are scoping the work needed to deliver support for Jira Server first then Jira Cloud.
This is a look ahead for the next iteration (about 3 months) that we have planned for the category:
Apart from improving the import by direct transfer ourselves, we recently published a step-by-step guide for adding a new relation to the importer, so that everyone can contribute. Gitlab Product groups and Community Contributors are invited to check out the guide and try adding a missing resource. The resources that are most looked after are listed in this feature matrix. We’re looking to the feedback on how we could improve the guide and make this process even more streamlined.
These are highlights from the current month's planned work:
Group Import continuously evaluates and updates the Importers' direction and roadmap. As part of that effort, new Importers such as Trello and Azure DevOps (TFS) are being discussed. While these discussions may ultimately lead to the implementation of a new feature or a new Importer, none of them are being planned at this time.
Given our focus on migrating GitLab groups and project by direct transfer (general availability and beyond) we are not prioritizing work that is not in scope of that effort.
Group Import is not focused on the ability to regularly back up and restore your GitLab data, for example nightly backups of all your data. For more information on this use-case, please see the Backup and Restore category direction page.
BIC (Best In Class) is an indicator of forecated near-term market performance based on a combination of factors, including analyst views, market news, and feedback from the sales and product teams. It is critical that we understand where GitLab appears in the BIC landscape.
This table provides a quick overview of what GitLab importers exist today and which most important objects they each support. This list is not exhaustive and the detailed information can be found on the Importers documentation page.
| Import source | Repos | MRs | Issues | Epics | Milestones | Wiki | Designs | API * |
|---|---|---|---|---|---|---|---|---|
| Group and project migration by direct transfer | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Group migration with export files (deprecated) | ➖ | ➖ | ➖ | ✅ | ✅ | ➖ | ➖ | ✅ |
| Project migration with export files | ✅ | ✅ | ✅ | ➖ | ✅ | ✅ | ✅ | ✅ |
| GitHub | ✅ | ✅ | ✅ | ➖ | ✅ | ✅ | ➖ | ✅ |
| Bitbucket Cloud | ✅ | ✅ | ✅ | ➖ | ✅ | ✅ | ➖ | ❌ |
| Bitbucket Server | ✅ | ✅ | ❌ | ➖ | ❌ | ➖ | ➖ | ✅ |
| Gitea | ✅ | ✅ | ✅ | ➖ | ✅ | ➖ | ➖ | ❌ |
| Git (Repo by URL) | ✅ | ✅ | ➖ | ➖ | ➖ | ➖ | ➖ | ❌ |
| Manifest file | ✅ | ✅ | ➖ | ➖ | ➖ | ➖ | ➖ | ❌ |
| CSV | ➖ | ➖ | ✅ | ➖ | ➖ | ➖ | ➖ | ❌ |
| FogBugz | ➖ | ➖ | ✅ | ➖ | ➖ | ➖ | ➖ | ❌ |
* This column indicates whether this importer is accessible via API, in addition to the UI.
While the long-term goal for the Import group is to provide all the GitLab importing capabilities needed by our customers in our application, we recognize that GitLab's current capabilities may not support specific migration scenarios. Often, we're not aware of these requirements until a large customer provides us with specific migration requirements.
GitLab Professional Services team uses Congregate tool to orchestrate user, group, and project import API calls in order to help customers automate scaled migrations. With the feature of migrating groups and projects by direct transfer ready for production use at any scale, we will be able to substitute the part of Congregate handling migration on groups and projects.