How do I set up the Jira integration for the first time?
Follow the Integrating Craft.io and Jira setup guide. Before you start, make sure you have:
Your Jira site URL
An API token from your Atlassian account (id.atlassian.com)
Admin access to both Craft.io and Jira
The integration is configured once at the workspace level - individual team members do not need to set it up separately.
I can't see the Jira integration option in my settings - where is it?
The Jira integration is found under Workspace Settings > Integrations > Development Tools. If you cannot see it:
Confirm you have Admin access - only workspace Admins can view and configure integrations
My Jira sync is stuck or not working - how do I troubleshoot?
Start with the most common causes:
API token expired or revoked - go to Workspace Settings > Integrations > Jira and update the token
Webhook not firing - verify the webhook is still active in Jira under Project Settings > Webhooks and has not been deleted or paused
Field or type mapping conflict - open a stuck item in Craft.io and check the Sync Status in the item panel for an error message
If the sync is stuck at a percentage and not progressing, contact support to assist with a re-sync.
The sync button is greyed out - why?
A greyed-out sync button usually means the item type mapping has been lost or the integration connection has dropped. To fix it:
Go to Workspace Settings > Integrations > Jira and check that the project mapping is still intact
If mappings have disappeared, re-configure them and save
If the connection itself has dropped, re-authenticate using your API token
If the button remains greyed out after re-saving the mapping, contact support with the affected item ID.
Our Jira sync stopped working after a team member left - what do I do?
The Jira integration runs on the credentials of whoever configured it. If that person's Atlassian account has been deactivated or their API token revoked, syncing will stop entirely. To restore it:
Generate a new API token from an active Atlassian account with the required Jira permissions
Go to Workspace Settings > Integrations > Jira and update the API token and email address to the new account
Save and verify that sync resumes
It is good practice to tie the integration credentials to a shared service account rather than an individual's personal Atlassian account.
How do I link an existing Craft.io item to an existing Jira issue?
This is not currently supported. There is no way to manually connect an existing Craft.io item to an existing Jira issue.
The integration works by creating and linking items in one direction. Either:
Push from Craft.io - syncing a Craft.io item creates a new issue in Jira, linked to that Craft.io item
Pull from Jira - syncing from Jira creates a new item in Craft.io, linked to the original Jira issue
If you have items that already exist in both tools independently, they won't be merged or connected. We'd recommend deleting one and re-creating it via sync.
My stories are syncing to Jira as SubTasks instead of Stories - how do I fix this?
This happens when the item type mapping sends Stories to a Jira issue type configured as a child type (SubTask) in your Jira project. To fix it:
Go to Workspace Settings > Integrations > Jira > Item Type Mapping
Update the mapping so Craft.io Stories point to the Story issue type in Jira, not a SubTask type
Re-sync affected items after saving the updated mapping
Stories are syncing to Jira but are not linked as parent/child - why?
This can happen when the parent item has not been synced to Jira before the child items. To resolve it:
Make sure the parent item (Epic or Feature) is synced to Jira before syncing its children
Check that the Epic field is included in your field mapping under Workspace Settings > Integrations > Jira > Field Mapping
If the hierarchy is still not preserved after re-syncing, contact support with the affected item IDs
Can Craft.io sync to multiple Jira projects?
Yes. Each Workspace in Craft.io can connect to multiple Jira projects/spaces, so teams with separate Jira backlogs can each connect to their own project. Configure
How do I control whether sync is automatic or manual?
Go to Workspace Settings > Integrations > Jira to configure sync behavior. You can set:
Manual sync - items are only pushed or pulled when you trigger it explicitly from the item panel
Automatic sync - changes in Jira are reflected in Craft.io automatically via the webhook, and changes in Craft.io are pushed to Jira without manual action
Many teams use automatic sync from Jira to Craft.io, but keep Craft-to-Jira as manual to control when new items are created in their Jira backlog.
Can Craft.io sync Initiatives from Jira?
Yes. Initiatives are only available in Jira Premium (via Advanced Roadmaps). If you are on Jira Premium, Initiatives can be mapped and synced with Craft.io. If you are on a standard Jira plan, Initiatives are not available as a native issue type and cannot be synced.
Contact your Customer Success Manager if you need help configuring Initiative mapping after upgrading to Jira Premium.
Does Craft.io support Jira on-premise (server)?
Yes. Jira Data Center is supported on Enterprise plans. The Starter and Pro plans only support Jira Cloud. If you are on Jira Data Center, your network will also need to allowlist Craft.io's IP addresses - contact support@craft.io for the current IP list.
How do I update my Jira API token?
Go to Workspace Settings > Integrations > Jira and update the API token field. To generate a new token:
Log in to id.atlassian.com and navigate to Security > API Tokens
Create a new token and paste it into Craft.io
Note: after updating the token, it can take up to 30 minutes for the new credentials to fully propagate and for syncing to resume.
Who can access and change the Jira integration settings?
Only workspace Admins can view and modify integration and mapping settings. Editors and viewers do not have access to Workspace Settings. If a team member needs to adjust mappings, they will need to be granted Admin access first.
If I unsync a Craft.io item from Jira, can I resync it later?
Yes. Unsyncing removes the active link but does not permanently break the connection or delete items in either tool. You can re-trigger a sync from the item's three-dot menu. Historical changes made while the item was unsynced will not be backfilled.
What happens in Jira when I convert a Craft.io item type?
If you convert a synced item in Craft.io (for example, from a Deliverable to an Epic), Craft.io will attempt to update the corresponding Jira issue type based on your current item type mapping. If the new type is not mapped, the sync will fail for that item. Check your item type mapping after any conversion to confirm the new type has a valid Jira equivalent.
How do I map custom fields from Jira to Craft.io?
Go to Workspace Settings > Integrations > Jira > Field Mapping and add a mapping between the Jira field and the corresponding Craft.io field.
See Mapping story point values between Craft.io and Jira for reference on how field mapping works for story points
Which IP addresses does Craft.io use to connect to Jira?
If your organization requires IP allowlisting for Jira access, contact support@craft.io to get the current list of Craft.io IP addresses. This is required for on-premise or network-restricted Jira environments.
How do I use JQL to filter which Jira issues sync to Craft.io?
When setting up or editing your Jira integration, you can specify a JQL filter to control which issues are imported. This is useful for limiting the sync to specific projects, issue types, or statuses. See Using JQL to import issues from Jira for full guidance.