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 | 2022-09-15 |
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 self-managed GitLab to GitLab.com.
Our goal is to build importers that our customers find valuable, reliable and easy to use, thereby removing friction for migrating to GitLab and creating a more 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 GitLab Migration, which is migration of groups and projects from one GitLab instance to another, as well as on importers for other software development tools like GitHub or Bitbucket.
Jira Integration is owned by the Ecosystem: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 the upcoming year we will be focused on two main areas:
This work can be tracked in gitlab&2771. We are way on our path to reach the Complete maturity level when the GitLab Migration is able to migrate entire groups along with all of their child subgroups and projects in a single click. It will also be possible to migrate users, which has been identified as the highest priority gap in the single Group and Project importers functionality.
This is the planning epic to reach the Complete maturity level for GitHub Importer. Currently we are working on releasing the option to migrate issue events and pull request events history, this includes events like: who added/removed labels, milestones, assignees, etc.
The next effort will be translating GitHub rules for protected branches into GitLab rules and apply them in imported projects and adding the functionality to cancel project import form GitHub.
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 GitLab Migration 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.
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 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 - GitLab Migration.
With GitLab Migration we aim for a first-class GitLab-to-GitLab migration experience.
Once GitLab Migration reaches feature parity with the single Group and Project importers, these file-based solutions will be disabled by feature flag, and only the GitLab Migration 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 GitLab Migration, which requires a direct connection between the migrated instances, until we extend the GitLab Migration 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 completed GitLab Migration we will be able to retire Congregate.
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.