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.
| Section | Maturity | Last Reviewed |
|---|---|---|
| Dev | Non-marketable | 2023-01-16 |
The Importers direction page belongs to Import group within the Manage Stage of the Dev section, and is maintained by Magdalena Frankiewicz.
This vision is a work in progress and everyone can contribute. If you'd like to provide feedback or contribute to this vision, please feel free to comment directly on issues and epics at GitLab.com.
The mission of the Importers category is to provide a great experience migrating from other applications in our customer's DevOps toolchains. This also includes GitLab-to-GitLab migrations, particularly from self-managed GitLab instances to GitLab.com.
Our goal is to build importers that our customers find valuable, reliable and easy to use. We aim to remove frictions for migrating to GitLab and create a positive first impression when adopting GitLab.
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.
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 Manage: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.
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.
In 2023 we will focus on two areas:
Users should be able to migrate all groups they own with their projects from one instance of GitLab to another at once. Our goal is to provide an easy to use tool that recovers gracefully from errors and imports over nearly 100% of relevant objects.
This work can be tracked in gitlab&2771.
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 destination instance. We have been working to extend this functionality to projects and we are launching the ability to migrate projects by direct transfer as a beta in GitLab 15.8. This beta feature is available to everyone. It is enabled by default on GitLab.com. GitLab self-managed users can access the feature when instance administrator enables:
bulk_import_projects feature flag, for migrating projects in the groups.This is a major improvement from migrating groups and projects using file exports because:
In the upcoming milestones we plan to focus on:
Next, we will be focusing on:
If you have any feedback regarding migrating groups and projects by direct transfer, please comment on this feedback issue.
Users should be able to reliable and scaleable import all relevant GitHub concepts for projects of all sizes. We track the work in this planning epic.
In the upcoming milestones we plan to focus on:
In the next milestone we want to:
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.
Planned removal: GitLab 16.0, 2023-05-22.
WARNING: This is a breaking change. Review the details carefully before upgrading.
The Phabricator task importer is deprecated in GitLab 15.7. Phabricator itself as a project is no longer actively maintained since June 1, 2021. We haven't observed imports using this tool. There has been no activity on the open related issues on GitLab.
Planned removal: GitLab 16.0, 2023-05-22.
The GitLab.com importer is deprecated in GitLab 15.8 and will be removed in GitLab 16.0. The GitLab.com importer was introduced in 2015 for importing a project from GitLab.com to a self-managed GitLab instance through the UI. This feature is available on self-managed instances only. Migrating GitLab groups and projects by direct transfer supersedes the GitLab.com importer and provides a more cohesive importing functionality.
See migrated group items and migrated project items for an overview.
Planned removal: GitLab 16.0, 2023-05-22.
The Rake task for importing bare repositories gitlab:import:repos is deprecated in GitLab 15.8 and will be removed in GitLab 16.0.
This Rake task imports a directory tree of repositories into a GitLab instance. These repositories must have been
managed by GitLab previously, because the Rake task relies on the specific directory structure or a specific custom Git setting in order to work (gitlab.fullpath).
Importing repositories using this Rake task has limitations. The Rake task:
gitlab.fullpath set. Epic 8953 proposes removing support for this setting.Alternatives to using the gitlab:import:repos Rake task include:
Planned removal: GitLab 16.0, 2023-05-22.
WARNING: This is a breaking change. Review the details carefully before upgrading.
The ability for users with the Developer role for a group to import projects to that group is deprecated in GitLab 15.8 and will be removed in GitLab 16.0. From GitLab 16.0, only users with at least the Maintainer role for a group will be able to import projects to that group.
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 * |
|---|---|---|---|---|---|---|---|---|
| GitLab Migration | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Group Import/Export | ➖ | ➖ | ➖ | ✅ | ✅ | ➖ | ➖ | ✅ |
| Project Import/Export | ✅ | ✅ | ✅ | ➖ | ✅ | ✅ | ✅ | ✅ |
| GitHub | ✅ | ✅ | ✅ | ➖ | ✅ | ✅ | ➖ | ✅ |
| Bitbucket Cloud | ✅ | ✅ | ✅ | ➖ | ✅ | ✅ | ➖ | ❌ |
| Bitbucket Server | ✅ | ✅ | ❌ | ➖ | ❌ | ➖ | ➖ | ✅ |
| Gitea | ✅ | ✅ | ✅ | ➖ | ✅ | ➖ | ➖ | ❌ |
| Git (Repo by URL) | ✅ | ✅ | ➖ | ➖ | ➖ | ➖ | ➖ | ❌ |
| Manifest file | ✅ | ✅ | ➖ | ➖ | ➖ | ➖ | ➖ | ❌ |
| CSV | ➖ | ➖ | ✅ | ➖ | ➖ | ➖ | ➖ | ❌ |
| FogBugz | ➖ | ➖ | ✅ | ➖ | ➖ | ➖ | ➖ | ❌ |
| Phabricator | ➖ | ➖ | ✅ | ➖ | ➖ | ➖ | ➖ | ❌ |
* This column indicates whether this importer is accessible via API, in addition to the UI.
Importers is a non-marketable category, and is therefore not assigned a maturity level. However, we use GitLab's Maturity framework to visualize the current state of the high priority importers and discuss their future roadmap. Generally speaking:
The historical, but still in use GitLab group and project importer functionality consists of two separate importers, the (single) group import/export and (single) project import/export. Together, they allow for group and project migrations between two instances of GitLab using data files, one group/project at a time.
Migrating an entire group with projects therefore requires coordination of multiple exports and imports, including some manual data manipulation and user configuration. This user experience creates a lot of friction.
Both the single group and the single project importers are available through the API and the UI and most of the objects in each are being exported and imported, which makes them a Viable feature in GitLab.
We have recognized that larger customers have needs that exceed the capabilities of those file-based importers. Therefore, we are focused on developing a fast and scalable replacement where group with all their subgroups and projects can be migrated by direct transfer.
With this method of migrating GitLab groups and project we aim for a first-class GitLab-to-GitLab migration experience.
Once migrating groups and projects by direct transfer is ready for production use at any scale (currently we are preparing for releasing to open beta), the single group and single project import/export will be disabled by feature flag, and only migrating groups and projects by direct transfer will be available in the UI and API. At first, customers that are using air-gapped networks, with no network connectivity between their GitLab instances, will need to enable the export/import solution. They won't be able to use the new way of migrating groups and projects, as it requires a direct connection between the migrated instances, until we extend this solution to support also the air-gapped solutions.
The GitHub Importer is currently a Viable feature in GitLab. It is accessible through both the API and the UI and uses a direct link to the GitHub server to import the highest priority objects, such as merge requests, issues, milestones and wiki pages, in addition to the repository.
The Bitbucket Cloud Importer is currently a Viable feature in GitLab. It is accessible through the UI and uses a direct link to the Bitbucket Cloud repository to import the highest priority objects, such as merge requests, issues, and milestones, in addition to the repository.
There is currently no ongoing work to achieve the Complete maturity level for Bitbucket Cloud Importer. This maturity level would include most of the available objects and ability to invoke the import via the API.
The Git Importer is currently a Complete feature in GitLab. This is a basic importer that migrates any Git repository into GitLab. Most of our competitors (i.e. GitHub, Microsoft Azure, Atlassian Bitbucket) only offer this type of importer.
There is currently no ongoing work to achieve the Lovable maturity level for Git Importer. This maturity level would include an improved user experience.
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.
If you'd like to contribute feedback on areas you'd like to see prioritized, please add them as comments in the corresponding epic for this category.