Summary

The website content details the process of migrating issues from Jira to Gitlab, including the challenges faced and the solutions implemented, within a company that has undergone mergers and is standardizing its engineering toolchain.

Abstract

The company described has consolidated from three separate entities, each with its own tools and processes, leading to inefficiencies. To address this, the decision was made to standardize on Gitlab for the entire development lifecycle, recognizing its strong CI/CD capabilities. However, the transition presented challenges, particularly in reconciling the permissions model and the decoupling of source code from issues, as was possible in the Atlassian suite with Jira and separate code repositories. The company's team structure, based on functional areas rather than specific projects, added complexity to the migration. The Gitlab Jira Importer was deemed unsuitable due to the company's use of the component field in Jira and the need to accommodate a backend and frontend team working across multiple projects. Consequently, a custom script was developed, leveraging the APIs of both Jira and Gitlab, to handle the nuanced migration requirements. This script addressed multiple components in Jira issues, the recreation of epics in Gitlab, and the preservation of the original reporter in the issue description. It also included migration tracking to avoid duplication. The final script, which can be found on GitHub, was tailored to meet the specific needs of the company's migration process.

Opinions

The author views Gitlab's investment in CI/CD as a significant advantage and believes it will streamline the engineering process.
The permissions model in Jira, which allows separate access to issues and source code, is seen as a positive feature that Gitlab's integrated approach initially struggled to accommodate.
The Gitlab Jira Importer's limitations were a disappointment, particularly its inability to handle the company's multi-project team structure effectively.
The author expresses gratitude for the existing script by Manish Jain, which served as a starting point for their custom migration script.
The lack of SUDO functionality in the hosted Gitlab instance is seen as a drawback, as it leads to the loss of the original "reporter" of the issue during the migration.
The author considers the ability to handle issues with multiple components, bring over epics, and adjust the description of new issues as essential enhancements to the migration script.
The addition of migration tracking to the script is seen as a critical feature to prevent the duplication of issues during the migration process.

Migrating Issues from Jira to Gitlab

The company where I work is a culmination of 3 different software companies that have merged into one over a two year period. Each organization had their own processes, procedures and toolchains which caused some challenges and inefficiencies. The decision was made to standardize our engineering toolchain across all of the product lines.

After a trial of a few different solutions out there it was decided that we would migrate everything to Gitlab.

Gitlab has really made an investment into CI/CD and it shows, being able to have a single solution for the entire lifecycle of development will streamline our engineering process. All of these efficiencies don’t come without some challenges though. The biggest hurdle we found was the permissions model and strict coupling of source code to issues. In an Atlassian world Jira and your code repo are two different authentication sources with their own permissions so it was easy to allow someone access to issues without giving them access to source code. This and the way that our teams our structured based on functional area rather than specifically tied to a single project proved challenging but not unsurmountable tasks.

Once we got through the permissions and were happy with that, it was time to look at migrating the issues out of Jira into Gitlab.

Option 1: The Gitlab Jira Importer

This was not a viable option for us due to the way that we have our teams broken down for some products. We have a backend team and frontend team and they can work across multiple projects. In Jira, unfortunately we were big users of the component field.

The Gitlab Jira importer would take all of the issues out of a specific Jira project and import them into a Gitlab. The importer would also map the usernames over so you didn’t lose any history there. This was nice, but given that we have quite a few older Jira issues that were for both the frontend and backend teams this didn’t work for us.

Option 2: A Script

After determining that Option 1 wouldn’t work, to Google we go. Given both Jira and Gitlab have robust APIs there were a number of options out there to assist. None of them were exactly what we needed but this script by Manish Jain was the closest, thank you for posting your work to get me started!

This script was used to migrate to an on-premise Gitlab instance which does have a few differences, the biggest one being that it allows for the SUDO concept. Host Gitlab does not, that feature is reserved only for a few Gitlab employees. While that makes sense it does cause me to lose the original “reporter” of the issue during the migration.

It was decided that this was going to be acceptable for the import as long as we added that information to the description of the imported issue.

The Import Script

The base script used straight API calls which I found at times didn’t produce the exact results I was looking for. I found the python-gitlab module which worked spot on for me. It does support SUDO, however being that we are on a hosted instance of gitlab.com I did not try that out.

The base script had the ability to add issues to a milestone but we are using Iterations instead of milestones and unfortunately there isn’t an API to create new iterations yet from Gitlab so I disabled that section of the code.

Handling issues with multiple components

The first challenge I needed to solve was dealing with tickets that had multiple components associated with a single Jira issue. The script will look at the components and map them out to the correct Gitlab project and create an issue in both projects. This not only solves my issue but cleans things up and allows us to track work better, so win for the migration.

The second item I wanted to address that wasn’t handled by the original script was the ability to bring over the epic. The original script was just adding a label for the epic to the new issue but I wanted to recreate the epic and associate the issues to the correct one.

The third enhancement was adjusting the description of the newly created issue. The original script added comments to the issue with a link to the Jira issue as well as a comment for the sprint information. The comments were nice but I wanted to have that in the original description along with the original reporter.

The final enhancement I added was migration tracking. I wanted to ensure that in the event my script died or I needed to re-run it that the script wouldn’t add in the same issues again.

The code for this script can be found here. I am sure there is more I can add to the script but this was sufficient for our needs.