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 | Manage |
| Maturity | N/A |
| Content Last Reviewed | 2023-22-05 |
Thanks for visiting this category direction page on Importers in GitLab. This page belongs to the Import and Integrate group of the Manage 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, build pipelines, 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 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 exeprience.
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 GitHub to GitLab or from self-managed GitLab instance to GitLab.com 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, planning tools, CI/CD tools, and source control tools.
The Import group is focused on migrating groups and projects from one GitLab instance to another, as well as on importers from other software development tools like GitHub or Bitbucket.
Jira Integration is owned by the Manage:Integrations group and the Jenkins Importer is owned by the Verify:Pipeline Authoring group.
In 2023, we want to reach a production-quality, easy to use tool for migrating GitLab resources between instances of GitLab. It should gracefully recover from errors and import over nearly 100% of relevant objects.
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. This beta feature is available to everyone, enabled by default on GitLab.com and with some configuration on self-managed GitLab instances. You can read more about the benefits of the method and how to use it in a blog post or directly check the tool's documentation.
Work on migrating GitLab resources by direct transfer can be tracked in gitlab&2771 and is layed out in more deatils in epics:
If you have any feedback regarding the tool, please comment on this feedback issue.
What about migrating projects using file exports?
Once the migrating projects by direct transfer feature is ready for production use at any scale, migrating groups and projects using file exports will be disabled by a feature flag and only migrating groups and projects by direct transfer will be available in the UI and API.
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 will need to reenable migrating using file exports. They will be able to use migrating groups and projects by direct transfer after we extend this solution to also support offline instances.
We will not fully remove migrating using file exports until we support all our customers with a new solution.
In 2023 we also continue the work to obtain the feature parity and complete maturity of GitHub importer(documentation).
More details in epics:
This is a look ahead for the next iteration (about 3 months) that we have planned for the category:
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, CircleCI, Subversion 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 and completing the GitHub importer, we are not prioritizing any work that is not in scope of these two efforts. This includes all other importers, as well as issues for GitHub Importer which are not related to our focus area.
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.
In the 2023 we aim to first of all release migrating projects by direct transfer to general availability (currently it is in Beta) by working to:
In pararel we continue the work to obtain the feature parity and complete maturity of GitHub importer.
After reaching general availbility of GitLab migration by direct transfer, we will work on migrating users and importing more of relevant GitLab resources.
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.