Introduction to Migrating from Linear to JIRA

Why would you want to migrate from Linear to JIRA?

At our company we started to realise that we needed more of Jira's heavy duty features that Linear doesn't provide. Mainly things like burn-down charts and estimation tools. We also wanted to take better advantage of Jira's first party integrations into the Jira Product Discovery and Jira Service Management.

How to go about it?

Migrating from Linear to JIRA is a fairly complex journey with multiple phases. A colleague and I ended up writing a number of scripts and tools to help us manage the process. I have chosen to make these tools open source so that others who go through this process might be able to navigate it more easily. The tools are available both on Github and on my personal Gitea instance.

The below diagram shows a mapping of the scripts that are involved in this process and their dependencies upon each other.

Export Issues from Linear

The first step in the process is to export your initial set of issues from Linear using the built in UI. This will generate a CSV file containing issue information that you can use to feed into subsequent processes.

Install and Configure the Python Scripts

You will need to install a compatible version of Python and the associated dependencies before you'll be able to run any of the scripts.

Create API Keys

You will need an API key that the Python scripts can use to access your Linear account and an API key that link importer can use to communicate with JIRA. If you have attachments that you want to copy over you will also need an Ngrok API key or credentials for copying the files somewhere public such as a GCP or S3 bucket or an FTP server. 

Export Projects, Attachments, Comments and External Links

Once we have a Linear API key in place we can start to export these things via the GraphQL API. The provided scripts will automatically extract everything we need and write it to a CSV file.

Host Attachments

In order for Jira to find the attachment files they must be hosted somewhere public.

Generate JIRA Import JSON

Once we have set up a config.yaml configuration file we can use all of the previous steps to generate a JSON file to be uploaded to JIRA.

Import External Links

After everything has been imported into JIRA we can import any external links into the platform.