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:

JiraLinear
SummaryTitle
DescriptionConverted into markdown and used as issue description
AssigneeAssignee (best effort match)
CreatorCreator (best effort match)
PriorityPriority
Issue KeyUsed in backlink, or matched (see article)
Issue typeMapped to the most similar Linear status
TypeLabel (team-level)
EpicProject
CommentsComments
EstimateEstimate
Due dateDue date
Parent/ChildParent/sub-issue
LabelLabel
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 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.

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. If you've already imported from that project and wish to re-import it as synced, delete the import from Settings > Import/Export, configure the sync and re-import.

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.

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

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.

The CSV file must only contain issues form a single Jira project (otherwise, keys could contain conflicting numbers.) You must also be importing to a new team in Linear rather than an existing team.

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.

  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 or create a Linear team to receive the imported data
  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.
  • Import stale issues (not updated in 6 months) to your archive, or not to import them.
  • map each Jira user to an existing Linear user, invite Jira users to your Linear workspace, or take no action for certain Jira users.
  1. Export a CSV from Jira by searching under advanced issue search in JQL (project=TEST, for instance).
  2. Export the data as a CSV and choose the "all fields" option.
  3. Attach this file in Linear where prompted and optionally add data in the other requested fields.