Jira migration options

You have several options to migrate your Jira projects to GitLab. Before you decide on a migration strategy, first decide if you even need to move your Jira issues to GitLab. In many cases, the Jira issue data is no longer relevant or actionable. By starting fresh in GitLab, you can focus on setting up your processes and workflows to maximize the advantages of using GitLab.

If you opt to migrate your Jira issues, you can choose from several migration options:

  • Use GitLab Jira importer.
  • Import a CSV file.
  • Let GitLab Professional Services handle the migration for you.
  • Use a third-party service to build a one-way or two-way data synchronization process.
  • Use a third-party script.
  • Write your own script.

Use GitLab Jira importer

GitLab has a built-in tool to import your Jira issue data. To use the GitLab Jira importer:

  1. Configure the GitLab Jira integration in your target project
  2. Import your Jira project issues to GitLab

Alternatively, you can watch a complete demo of the process: Import Jira project issues to GitLab

Import a CSV file

To import the Jira issue data from a CSV file into your GitLab project:

  1. Export your Jira data:
    1. Log in to your Jira instance and go to the project you want to migrate.
    2. Export the project data as a CSV file.
    3. Edit your CSV file to match the column names required for the GitLab CSV importer.
  2. Create a new GitLab group and project:
    1. Sign in to your GitLab account and create a group to host your migrated projects.
    2. In the new group, create a new project to hold the migrated Jira issues.
  3. Import the Jira data into GitLab:
    1. In your new GitLab project, on the left sidebar, select Plan > Issues.
    2. Select Actions () > Import from Jira.
    3. Follow the on-screen instructions to complete the import process.
  4. Verify the migration:
    1. Review the imported issues to ensure the project migrated to GitLab successfully.
    2. Test the features of your migrated Jira project in GitLab.
  5. Adjust your workflows and settings:
    1. Customize your GitLab project settings, such as description templates, labels, and milestones, to match your team’s needs.
    2. Familiarize your team with the GitLab interface and any new workflows or processes introduced by the migration.
  6. Decommission your Jira instance:
    1. When you’re satisfied with the migration, you can decommission your Jira instance and fully transition to GitLab.

Let GitLab Professional Services handle the migration for you

For a high-level overview of the Jira migration service, see the Jira Migration Service data sheet.

To get a personalized quote, visit the GitLab Professional Services page and select Request Service.

Establish a one-way or two-way data synchronization using a third-party service

To establish a one-way or two-way data synchronization between Jira and GitLab, you can use the following third-party services:

Use a third-party script

You can use one of the available open-source migration scripts to help you migrate your Jira issues to GitLab.

Many of our customers have had success using jira2gitlab.

View a complete demo of the process: Migrating from Jira to GitLab with Jira2GitLab

Write your own script

For full control over the migration process, you can write your own custom script that migrates your Jira issues to GitLab in a way that suits your needs exactly. GitLab provides APIs to help automate your migration:

To get started, familiarize yourself with the following GitLab API endpoints:

When writing your script, you need to map the Jira issue fields to their corresponding GitLab equivalents. Here are some tips:

  • Custom fields with a fixed number of options: Create a scoped label set with the field name as the scoped label key and the field values as the scoped label set values (for example, input name::value1, input name::value2).
  • Custom fields with text strings or integer values: Inject the custom field name and value into a section in the issue’s description.
  • Status: Create a scoped label with the status set as the scoped label key and the status values as the scoped label set values (for example, status::in progress).
  • Priority: Create a scoped label with the priority set as the scoped label key and the priority values as the scoped label set values (for example, priority::1).
  • Story Point: Map this value to the GitLab issue’s weight value.
  • Sprint: Map this value to the GitLab issue’s iteration value. This value is meaningful only for issues that have not been completed or are scheduled for a future sprint. Before importing the data, create the required iterations in the parent group of your project.

You might also need to handle parsing the Atlassian Document Format and mapping it to GitLab Flavored Markdown. You can approach this in many different ways. For inspiration, review an example commit. This commit added a method to parse the Atlassian Document Format to GitLab Flavored Markdown for the GitLab Jira importer.

If you run GitLab locally, you can also convert Atlassian Document Format to GitLab Flavored Markdown manually in the Rails console. To do so, execute: 

text = <document in Atlassian Document Format>
project = <project that wiki is in> or nil
Banzai.render(text, pipeline: :adf_commonmark, project: project)