This article walks Workspace Admins through the full end-to-end setup of the native Craft.io and Jira integration, from authentication to bidirectional sync.
Before you start
To complete this setup, you will need:
Admin access in your Craft.io Workspace.
Jira System Administrator permissions to manage access, API tokens and Webhooks.
A clear understanding of which Jira Projects and JQL filters are needed to scope your backlog.
💡 To integrate with an On-Premise/Server Jira instance, you may be required to whitelist Craft.io's Server IP addresses in your firewall. This lets Craft.io connect to your JIRA server to create work items.
Step 1: Align terminology between Craft.io and Jira (recommended)
By default, Jira follows a hierarchy (often Initiative > Epic > Story > Subtask) that may differ from your Craft.io configuration.
Craft.io allows teams to amend terminology to ensure both product and development teams speak the same language. While it’s possible to keep default settings in Craft.io, we strongly recommend taking five minutes to align your Craft.io hierarchy (e.g., renaming "Features" to "Stories") with Jira.
In your Craft.io Workspace settings:
Rename hierarchy levels (Epics, Features, or Stories) to match your Jira Issue Types
Align the Importance field in Craft.io with Jira’s Priority values
Enter into the 'System Fields' section in your Workspace Settings, and align your field values with Jira's Priority field values
Step 2: Create an API key in Jira
Open Jira and generate a Basic Authentication API token (access your Atlassian Settings via your Avatar).
Ensure the token owner has permissions to create, edit, and assign issues, as well as manage sprints and releases.
Copy the key and keep it safe; you will use this to allow Craft.io to read and write data.
💡 If you're integrating with On-Premise/Server Jira, you can skip this step, as a Username and Password is used in place of an API Token.
Step 3: Connect Jira in Craft.io
In your Craft.io Workspace
Open Settings > Integrations and Imports.
Click Connect on the Jira integration.
You will now configure authentication based on your Jira deployment type.
Jira Cloud (SaaS)
For Jira Cloud environments:
Enter your Jira URL
Enter the email address of the administrator who generated the API token
Enter the API Token created in Jira
Click Connect to establish the connection
Jira Server (On Premise)
Unlike Jira Cloud, Jira Server and Data Center environments do not use API tokens for this integration. For Jira Server or Data Center environments:
Enter your Jira URL
Enter the administrator username
Enter the administrator password
Click Connect to establish the connection.
Your IT team may need to whitelist Craft.io server IP addresses in your firewall. This allows Craft.io to securely connect to your Jira environment in order to create and update issues.
Craft.io IP addresses for whitelisting:
Production – US
35.232.112.68
34.36.93.194
Production – EU
34.89.210.62
35.244.168.88
Staging
34.70.139.232
💡 The user credentials provided for both Cloud and Server Jira integrations must have permission to create, edit, and assign issues within the selected Jira projects.
Step 4: Add Jira project integration
At this stage, select the first Jira Project to sync with. You will be able to add additional projects to the connection later on:
Click Add project integration
Select the Jira Project and relevant board
Click Next
Step 5: Define hierarchy mapping
Next, define how work items map between the two tools to ensure traceability from strategy to delivery. The below terminology aligns to Craft.io's out of the box hierarchy naming convention, but you can amend this to suit your preferred ways of working (see Step 1).
In the Craft.io Workspace:
Epics in Craft.io can map to Jira Initiatives or Epics
Features in Craft.io map into the corresponding items at the Story level in Jira (this includes bugs
Stories in Craft.io map into the corresponding items at the Task level in Jira
On the left of your Field and Type Mapping, you will see a reflection of your data model in Craft.io. Using the drop downs on the right, you can define which Jira item types map and update when synchronizing.
💡 Initiatives in Craft.io can map to Jira Initiatives, or the corresponding items up to two layers above in the hierarchy. This can be done in either the Workspace or Portfolio. Contact Craft.io customer success for more guidance.
Step 6: Field mapping overview
Craft.io automatically maps several core system fields, including:
Title and Description
Importance (Craft) → Priority (Jira)
Dev Assignee → Assignee
Sprints
In the following sections of the screen, you are able to map between fields in Craft.io and their corresponding fields in Jira.
You can map as many additional default and custom fields as needed, provided the field types match in both tools. This includes:
Primary fields: Jira Components, Story points, Releases, and Jira teams.
Default fields: Objective, Key result, Value, Effort, Labels and Dates
Custom fields - You can choose to map any custom field you create in Craft.io to Jira. Please note that the field types (text, single select, numeric, etc.) must be identical in both tools in order to map. This includes
Numeric fields such as custom capacity planning fields
Formula fields such as WSJF or priority Score
Single or Multi Select fields for T Shirt sizing or Priority
Custom time frame or milestone fields such as PI, Trimester or MVP launch
Step 7: Initial synchronization
Click Save and then Continue to sync to run your first import from Jira. This can also be done at a later stage, once you've completed steps 8 and 9 below.
Items are pulled based on your Jira Project and JQL selections.
JQL filtering (recommended): Use JQL to limit items imported into Craft.io (e.g., specific labels, components, or only "Open" items).
Include closed items (optional): By default, closed items are not imported; add them via JQL (Status = Closed) if needed for historical reporting
Imported items land in your Workspace, where you can move them between Product Areas to begin roadmapping
💡 To ensure the Jira Dev Assignee effectively maps into Craft.io, it's recommended that members of the engineering team have read-only (contributor) access in Craft.io. This will ensure their user details are captured upon sync from Jira, and does require a paid seat.
Step 8: Configure status mapping (for bi-directional sync)
While data fields (like names and descriptions) sync automatically, workflow progress and status do not. Without this step, your strategic roadmaps will drift away from engineering reality, requiring manual updates to track progress.
Go to Workspace Settings > Workflow and Statuses.
Map development-focused Jira statuses (e.g., "In Progress") to your chosen Craft.io phase (e.g., "Dev In Progress").
This ensures that real-time progress in Jira is effectively reflected in Craft.io
💡 Multiple Jira statuses can. be mapped into a single Craft.io status. Engineering teams often use 10+ granular statuses for execution. Mapping allows you to consolidate these into 4–5 "boardroom-ready" phases, providing executive clarity without the technical noise.
Step 9: Set up the webhook (for bi-directional sync)
The Webhook enables real-time updates from Jira to flow back into Craft.io without manual refreshing. This is a one-time action required by a user with Global Admin permissions in Jira, and does not require sharing any additional credentials in Craft.io.
In Craft.io: Copy the unique Webhook URL from the Jira integration settings.
In Jira: Go to System Settings > Webhooks and create a new webhook.
Paste the URL and apply the same JQL used in Step 4 to ensure only relevant updates flow back.
Select the following events: Issue Updated, Issue Created and Issue Deleted.
💡 If an item is deleted in Craft.io, a synchronized item is not deleted in Jira (and vice versa). In such a scenario, the connection is simply severed, and both items will remain active, but disconnected from one another. It is possible to re-sync these at a later stage.
Step 10: Verify the bi-directional sync
To confirm your bridge is active:
Update a field (like Title or Description) in Jira.
Confirm the update appears in Craft.io within seconds
Check the integration settings for a blue "Webhook Connected" indicator.
Updating and disconnecting the integration
Over time, you may need to update your integration settings. This commonly occurs when rotating API tokens or passwords for security reasons, or if the user whose credentials created the connection is no longer with the company.
Update credentials: You can refresh the API token, username, or password directly in the integration settings without disconnecting the connection.
Rename the connection: If branding or internal structure changes, you can rename the connection without affecting mappings or synced items.
Disconnect the connection: Disconnecting ends synchronization and removes project mappings. If the integration is later recreated, previously linked Craft.io and Jira items will not automatically reconnect.
💡 For long term stability and security, we recommend using a dedicated integration user (e.g admin@acme.com) rather than an individual employee account.
What comes next?
Now that your integration is setup, you'll be able to:
Push to Jira: Send prioritized Features and Epics from Craft.io to Jira to keep engineering focused on confirmed work.
Visualize Progress: Use the Progress Dashboard to see real-time rollups of Jira data.
Capacity Planning: Model delivery feasibility in Craft.io using the Story Points synced from Jira.
Need more guidance? 🙋 Our LIVE support team (at the bottom right corner of your screen) replies to ANY question!