Jira

Enable Jira Sync while trialing or transitioning to Linear to keep Jira spaces up to date.

To complete a one-time import from Jira to Linear, use the CSV or API credential options in importer. Imported issues import as synced only if the Jira integration is configured prior to completing your import. Switching from another tool? Follow our manual.

Overview

Some companies choose to import issues and switch to Linear immediately; others prefer to trial Linear on a small team first or need some time to make the full transition. For the latter cases, we built Jira Sync. This feature allows you to connect Jira spaces to Linear teams, so that new issues created in Jira or Linear are kept current in both places.

Permissions

The user creating the API token to enable Jira Sync must have the ADMINISTER permission in Jira. This is necessary for Linear to install the required webhooks. It is possible to remove the global ADMINISTER permission after the setup is complete without impacting this integration.

If the ADMINISTER holder does not have a Linear seat or does not want this permission stored in Linear, please see the FAQ.

Posting in a synced thread

In order to send a reply to a synced thread, you'll need to link your Atlassian account first.

Configure

Enable the integration in Linear from workspace settings under Workspace > Integrations > Jira.

Enter your personal access token (see Permissions > Setup above), email address and installation or cloud hostname and then select which Jira space to link to which Linear team. For the installation or cloud hostname, remember to remove the http:// and anything after .net.

For best performance, users should link their individual Jira accounts in Settings > Integrations > Jira > Connect personal account. This allows better handling of fields in Jira like Assignee and Creator.

Basics

Select Jira Spaces

We've set up the integration so that Jira spaces map to teams in Linear.

You can link each Jira space to only a single team in Linear, so the same space cannot create issues in multiple Linear teams. Multiple Jira spaces can be linked to the same Linear team though and issues will be created in Linear from any connected Jira space.

Relationship to Jira Imports

Running a Jira import will not automatically import issues as synced unless you've configured the Jira integration prior to the import. You do not need to create the space/team mappings prior to importing. For full instructions about importing issues as synced, please see our Importer documentation.

Synced properties

Once the integration is enabled, any new issue created in a linked Jira space or Linear team will create a synced version of that issue in the other service.

Sync directionality

When configuring the mapping between a Jira space and a Linear team, you have the choice of syncing uni-directionally or bi-directionally.

When syncing uni-directionally, issues created in Jira are also created in Linear. Changes made to that issue from Jira are synced to Linear, but changes made in Linear do not sync back to Jira.

When syncing bi-directionally, creating an issue in either service will create a synced copy in the other. Updating the synced copy in either service will sync changes back to the other issue.

Issue sync banners

Once an issue is synced between Jira and Linear, a banner will appear at the top of the issue to make this clear. The banners will display information to show current sync status or will surface any errors with syncing.

Limitations

There are a number of features in Jira that Linear has chosen not to pursue as a matter of product philosophy. These discrepancies are worth noting, as they will affect sync. Among these are Issue Type, Constraints, Components, and Required fields. Read more about how these differences are handled by sync below.

Issue filter

By default, Jira Sync will create and sync every issue that’s created in the mapped Jira space. If you wish to filter out some issues, you have the ability to do so by editing the webhook in Jira.

Please note that any JQL filters you applied to limit the scope of import do not apply for Jira Sync purposes. In order to change what is provided to Linear for Jira Sync, follow the instructions below:

Go to Settings → System → Advanced → Webhooks. Select the Linear webhook and click Edit.

The Issue related events box allows you to provide a custom JQL query to filter out some issues that you do not want to sync with Linear. This works both when the conditions are met at the time of the Jira issue's creation, as well as if the Jira issue is updated to meet the parameters of your filter later.

Here is an example to only sync issues with the label Bug:

Pre-sync issues in Jira

Once configured, Jira Sync will create issues in Linear when issues are created in a synced Jira space. Issues belonging to that synced space from before the sync was configured will not create issues in Linear.

However, when those issues receive updates in Jira, the updates will prompt those issues to be created and synced in Linear.

FAQ