Skip to content →

Importing from Jira

Import Jira projects as Linear teams.

Linear and Jira logos

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:

DescriptionConverted into markdown and used as issue description
AssigneeAssignee (best effort match)
CreatorCreator (best effort match)
Issue KeyUsed in backlink, or matched (see article)
Issue typeMapped to the most similar Linear status
TypeLabel (team-level)
ReleaseLabel (team-level)
Due dateDue date
StatusStatus (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 typeProsCons
API importsRetains 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 importsDoesn'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 matchingIf 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 but your broader organization is still using Jira, consider using Jira sync to reflect your team's work in Linear back to your broader org's Jira instance.

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.

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.

  1. 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
  2. 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.)

  • You are offered the option to either pick an existing team to import to, or to create a new team. Only the second option will match Jira IDs to Linear IDs.
  • You must check the boxes to import all the closed/done/archived issues as well. Otherwise, we will only import the active issues and the number scheme will start at whatever the highest was from the import.

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.

  1. Enter your personal access token (obtained from your Atlassian settings).
  2. Enter your project key
  3. Enter your email address you use for your Jira account.
  4. Enter your installation or cloud hostname. Remember to remove the http:// and anything following .net.
  5. Select the team you want the import to go to
  6. 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.