Jira
Enable Jira Sync while trialing or transitioning to Linear to keep Jira projects up to date.
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 projects to Linear teams, so that new issues created in Jira or Linear are kept current in both places.
G then S to go to Settings > Workspace > Integrations > Jira
Permissions
ADMINISTER permission
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.
Create an API key for this user by following instructions here
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 project 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 Projects
We've set up the integration so that Jira projects map to teams in Linear. You can link a Jira project to only a single team in Linear, but you can configure the integration so that multiple Jira projects create issues in one Linear team.
Relationship to Jira Imports
Running a Jira import will not automatically import issues as synced unless you've set up sync between those Jira projects to Linear prior to the import. 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 project or Linear team will create a synced version of that issue in the other service.
| Name in Linear | Name in Jira |
|---|---|
| Title | Title |
| Description | Description |
| Assignee* | Assignee* |
| Creator* | Creator/Reporter* |
| Priority | Priority |
| Status** | Status** |
| Labels*** | Labels*** |
| Due date | Due date |
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 project. If you wish to filter out some issues, you have the ability to do so by editing the webhook in Jira.
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 project. Issues belonging to that synced project from before the sync was configured will not create issues in Linear.
However, when those issues are receive updates in Jira, the updates will prompt those issues to be created and synced in Linear.