Jira
Enable Jira Sync while trialing or transitioning to Linear to keep Jira projects 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 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
Click the workspace menu and select Workspace Settings > Integrations > Jira
settings 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.
If the ADMINISTER holder does not have a Linear seat or does not want this permission stored in Linear, please see the FAQ.
Create an API key for this user by following instructions here. The default token expiry is one week, please choose to enable for a year instead.
API keys might not be available. Instead, you need to create a personal access token (or PAT). Instructions can be found here. The default token expiry is one week, please choose to enable for a year instead.
Posting in a synced thread
In order to send a reply to a synced thread, you'll need to link your Atlassian account first.
| Permission | What we use it for |
|---|---|
| User → View → me | We use this to capture the Jira Account ID of each user. This allows us to properly map users between Linear and Jira |
| User → View → me | This allows us to create issues and comments on behalf of the user. This does not grant access to read issues or comments not created by this user. |
Jira Server users will be presented with a simple form to input their own personal access token.
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 configured the Jira integration prior to the import. You do not need to create the project/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 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 |
* For these fields to sync successfully, the relevant user must connect their Jira account to Linear in Settings > Integrations > Jira Link. If no connection exists, the Assignee field will be unassigned, and/or the creator field will be the user who configured Jira Link.
** Deleting a synced issue in either Jira or Linear will not delete the issue in the other direction, or otherwise affect status in the synced issue.
If a synced issue in Jira moves to a status not in Linear, The Linear issue's status will not update. The status will update in Linear if the synced issue is moved in Jira to a status that can be mapped properly, or if the status is changed in Linear directly.
*** For labels to sync from Jira to Linear, the label must have already been created in Linear (either through a previous import, or by creating the label manually or through our GraphQL API. When labels sync from Linear to Jira, we'll create a new label in Jira when appropriate.
Sync directionality
When configuring a mapping between a Jira project 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.
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.
If a Jira project's workflow demands required fields, we will not create the synced issue in Linear. In the case where an issue has been created in Linear before required fields are enforced in Jira, we'll send an error to the Linear issue as a comment to surface the problem.
Issue type is a native required field in Jira. Bug, Story, Epic and Task are common issue types. When you create a new issue in Linear and we create a synced issue in Jira, it will be type Task if we find that type in Jira.
If this type has been deleted, we'll fallback to the first type on the list. If issues created in Linear are created in Jira as Story for instance, you may wish to create a type Task so that future issues created in Linear will display appropriately.
You may have constraints in Jira that prevent certain updates to a Jira issue until various conditions are met.
If you update a synced Linear issue in a way that violates Jira constraint, the Linear issue will update but the Jira issue will not.
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.
FAQ
Jira Sync is a forward looking integration -- it will create new issues in Linear or Jira when a new issue is created in a synced context in either service.
If you'd like to import your Jira issues as synced, please follow the steps here.
If you change metadata in synced Jira projects (delete, add, make them unrequired) this may cause the Jira issue and Linear issue to become out of sync.
Clicking the refresh button on the list of synced Jira projects in Linear settings will update the list of available projects, but also update the metadata to Linear's context. This is a fix forward; issues already out of sync because of missing metadata will not update after pressing this.
No, Issues imported to Linear in general will not create a synced copy in Jira. The specific exception to this is if you set up a synced Jira project in Linear and import from that Jira project to Linear.
Other imports outside of this will not create synced issues in Jira.
You may wish to triage Linear issues created by Jira instead of syncing their status automatically (for example, you may want the opportunity to decline the issue before admitting it to your backlog).
While this integration is broadly intended to keep Jira and Linear issues in sync, you can workaround this by renaming your first status under type Started something besides To do, to-do or similar variants. When the integration can't determine the right status at issue creation, it falls back to Triage. In other words, if your first started status is called "Started" in Linear and "To do" in Jira, new issues created by Jira in Linear will go to Triage.
This integration may also be setup with the webhook option. The actor who configures the webhook must still have ADMINISTER, but this can be done between two people synchronously -- A Jira ADMINISTER holder without a Linear seat, and a Linear admin with BROWSE PROJECTS permissions.
To do this, the Linear actor would choose the "Manual Webhook" option in Linear > Settings > Integrations > Jira
Then, the same person can fill this section:
On submission, they'll be presented with this form. They can then share the webhook URL and these instructions with the Jira ADMINISTER holder, who can setup the webhook in Jira directly:
After the webhook is setup, the Jira actor can securely share the webhook secret (through something like 1Password) to the Linear admin, who can input it where prompted and click Save. Any Linear admin can then manage the integration from within Linear.
Viewing the sync error will tell you more specific information about the root cause of the sync error. This can typically occur in cases where an issue is missing on Jira or your permissions are not configured correctly.
For permissions errors, using Jira's permissions helper can shed light on where the error lies.
Fill the values to:
- User: This should be set to the user who created the Jira Sync integration (you can check this in Linear in Settings > Integrations > Jira > Enabled by)
- Issue: Even though we are looking to check permissions to create new issues, the form requires us to pick an issue to check against. Choose any issue.
- Permission: Choose
Create issues. Then click submit and look for a status in the blue box, it should tell if that user has access to this permission on this project. If not, the details below should contain some clues about what's missing.