Jira import & sync

Linear offers two ways to bring work over from Jira, and understanding the difference upfront will save you time and avoid surprises.

Jira Import

A one-time migration that transfers your Jira projects, issues, and metadata into Linear. It carries over the broadest range of data, including issue relationships, epics (as Linear projects), and sprints (as cycles). See the feature mapping table below for a full breakdown of what’s supported.

Jira Sync

A continuous connection between the two tools, running in one or both directions. It’s designed for teams that need to keep working in Jira while others move to Linear, keeping information consistent across both platforms. Sync covers most core fields but has more limited support than import, particularly around issue relationships and estimates.

Key differences

Import fully supports issue relationship mapping (parent-child, blocking, relates-to), while sync has limited support for these.

For most teams, import is the right starting point. A clean cutover without sync is preferable where possible, as not all information syncs perfectly and some drift is inevitable. Only add sync if you have a clear, time-bound reason for it (for example, a partner team that isn’t migrating yet and needs visibility into your work).

The importer matches users by email address, not by role. If a Jira user’s email matches a provisioned Linear account, their assignee, creator, and mention data will carry over on imported issues. Users need to have signed in at least once for this to work (pending invites aren’t enough).

Each user should also connect their personal Jira integration at Preferences › Integrations › Jira. This is especially important if you’re using sync, as ongoing assignee and creator updates depend on this connection.

Jira roles and permissions don’t transfer to Linear. The two systems handle access differently, so roles need to be configured separately. See the Linear roles documentation for details on available role types and how to assign them.

Permissions needed for the migration itself

The person running the import needs an Admin role in Linear. If you’re also setting up Jira Sync, the user creating the API token needs the ADMINISTER permission in Jira (this can be removed after setup without affecting the integration).

Preparing for your import

We recommend doing your import as close to your team’s actual onboarding date as possible, so the data in Linear is fresh and relevant. Many teams use the migration as a fresh start, importing only in-progress or planned work and letting historical data continue to live in Jira.

Linear Admins can initiate an import from Workspace Settings › Administration › Import and Export. There are two methods available.

Using API credentials

This is the most common approach and the only method that supports enabling Jira Sync after import.

1. Enter your personal access token (obtained from your Atlassian settings)

2. Enter your project key

3. Enter the email address you use for your Jira account

4. Enter your installation or cloud hostname (remove the http:// and anything after .net)

5. Select or create a Linear team to receive the imported data

6. Click Next

You will then be guided through configuration options. 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

If you need to redo an import (and it’s fewer than 14 days old), you can delete it in Preferences › Import and Export next to the import. The same Jira projects can’t be imported twice, but imports can be easily undone.

Using a Jira CSV

If using API credentials is not feasible, you can also import using a CSV.

1. Export a CSV from Jira using advanced issue search in JQL (for example, project=TEST)

2. Choose the “all fields“ option when exporting

3. Clean up the CSV as needed, removing any issues or metadata you don’t want to bring into Linear

4. Attach the file in Linear where prompted and optionally fill in any additional requested fields

This table shows how Jira features map to Linear, what’s supported in import, and what carries over through sync.

The following Jira features have comparable equivalents in Linear, but they aren’t transferred automatically through import or sync. These will need to be set up manually as part of your Linear configuration.