Importing from Jira

Import Jira projects as Linear teams.

Data included in the import

We import data from Jira that matches a concept in Linear, and make some adaptations for other fields specified below:

Jira	Linear
Summary	Title
Description	Converted into markdown and used as issue description
Assignee	Assignee (best effort match)
Creator	Creator (best effort match)
Priority	Priority
Issue Key	Used in backlink, or matched (see article)
Issue type	Mapped to the most similar Linear status
Type	Label (team-level)
Epic	Project
Comments	Comments
Estimate	Estimate
Due date	Due date
Parent/Child	Parent/sub-issue
Label	Label
Status	Status (best effort conversion)

Please note that data not included above like custom fields or issue created dates will not import to Linear.

What import method should I choose?

Import type	Pros	Cons
API imports	Retains the most data, and permits use of Jira Sync functionality if enabled at the end of the import.	Requires Admin permissions in the source Jira project
CSV imports	Doesn't require high permissions in Jira to initiate, can be used to import many Jira projects at once if you don't need issue ID matching	If you wish to use Jira Sync, you must configure the connection prior to running the import

Both options will automatically label imported issues with "Migrated," are easily deletable within 7 days from Linear's Import/Export settings, and can support matching issue IDs.

You can also import through our CLI tool, but we don't recommend this for Jira as it doesn't import as much data, does not label imported issues and is not easily deletable if you wish to restart.

Considerations before importing

There are functionalities offered when importing from Jira that you may wish to know about in advance, as they'll affect decisions you make before or during your import

Syncing changes back to Jira

If your individual team is moving to Linear and your broader organization is still using Jira, Jira sync can help reflect your team's work in Linear back t Jira instance.

To import issues from Jira as synced, configure Jira links in Settings > Integrations > Jira for each of the Jira projects you're importing into Linear prior to running those imports.

You can also use the Back button at the top of the importer to set up your sync mappings when prompted. Once you've done so, return to Import settings, select configure import and select the Sync issues after import before continuing.

This sync feature will keep most issue properties aligned between the original issue in Jira, and the imported issue in Linear. Optionally, choose to enable bi-directional sync so that issues created in Linear will also sync to Jira (otherwise, only issues created in Jira will sync to Linear.)

For best performance in syncing fields like assignee and creator, individual Linear users should also connect their personal Jira accounts to Linear in integration settings prior to import as well. Please see the Mapping Jira users section for more information on this.

Running an import from a synced Jira project will import those issues as synced automatically.

Please see our Jira documentation for more information about Jira Sync

Mapping Jira users to Linear

The importer will attempt to match existing users in Linear to those you're importing from Jira. The optimal case is for users to already exist in both Jira and Linear with the same email address, and to have linked their Jira accounts in Settings > Integrations > Jira.

That said, often this is not the case in practice.

If a user is not yet in Linear, but has a valid email address in Jira: User will be treated as an external user and will be attributed as author of issues and comments, but not as the assignee
User's email address is unavailable: We cannot match these users. But if the user links their Linear and Jira accounts in Settings > Integrations > Jira and if the import is re-run, we might have a match.

Regardless of the scenario, re-running the import after users have joined will always help matching more users.

Matching Jira IDs in Linear

It's possible to have your issue IDs in Jira match in Linear (i.e. ENG-1 in Jira can be ENG-1 in Linear.)

During the import process you are offered the choice between importing to an existing team or creating a new team to hold your imported data. Only the second option will match Jira IDs to Linear IDs.

You must also check the boxes to import closed/done/archived issues for proper issue number matching.

Running the import

When you're ready to import, you can do so by heading to Linear's Import/Export settings. Please note that you must be a Linear Admin to run an import.

If you run into issues or need further assistance, please let us know at support@linear.app.

Enter your personal access token (obtained from your Atlassian settings).
Enter your project key
Enter your email address you use for your Jira account.
Enter your installation or cloud hostname. Remember to remove the http:// and anything following .net.
Select or create a Linear team to receive the imported data
Click Next

You will then be guided through configuration options during the import process. You will have the option to:

import into an existing team or a newly created team on your workspace.
map each Jira user to an existing Linear user, invite Jira users to your Linear workspace, or take no action for certain Jira users.

Importer

Initiatives Migration