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) |
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 in your Jira instance.
To import issues from Jira as synced, make sure the Jira integration is configured before completing your first import. If you plan to create a new team for your imported issues during the import (which will also allow matching Jira issue keys in Linear), you don't need to preconfigure team/project mappings in the Jira integration before importing.
During the import, ensure Sync issues after import in selected when prompted.
Unfortunately, issues imported from CSV cannot be synced with Jira, and will only appear as static copies of the issues at the time of import.
A link to the Jira issue will show in Linear so you can click through and check for updates, but changes in Jira or Linear will not be synced with this import type.
API-based import is recommended if you need to maintain a sync after 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.
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.
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.
- 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.
- 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.
- Export a CSV from Jira by searching under advanced issue search in JQL (project=TEST, for instance).
- Export the data as a CSV and choose the "all fields" option.
- Attach this file in Linear where prompted and optionally add data in the other requested fields.