This article walks Workspace Admins through the full end to end setup of the native Craft.io and Linear integration, from authentication to bidirectional sync.
Before you start
To complete this setup, you will need:
Admin access in your Craft.io Workspace
Permission in Linear to create an API token and a webhook
A clear understanding of which Linear teams should sync with Craft.io
💡 It's recommended to use a dedicated Linear user for the integration, such as craft-linear@yourcompany.com. This prevents sync issues if the original account holder leaves the company or their permissions change.
Step 1: Align terminology between Craft.io and Linear (recommended)
By default, Linear teams cannot edit values in system fields (such as Priority or Status), or change the name of items in the hierarchy. Craft.io allows teams to amend terminology, and modify values in system fields (such as Quarters, Sprints, Importance and Status).
Before integrating Craft.io and Linear, it is recommended to align the terminology between the two tools to ensure product and development teams can speak the same language.
In your Craft.io Workspace settings:
Rename hierarchy levels such as Epics, Features, or Stories to match Linear's Project, Issue and Sub-Issue workflow, if relevant.
Align the Importance field in Craft.io with Linear’s fixed Priority value.
Enter into the 'System Fields' section in your Workspace Settings, and align your field values with Linear's default Priority field values (see below).
Step 2: Create an API key in Linear
Open Linear and go to Settings
Navigate to Security and Access
Create a new API key and give it a name
Set permissions to Read and Write at a minimum
Define team access. Select all teams that may be relevant to your product workflow
Copy the key and keep it safe
You will use this key to authenticate the integration in Craft.io.
Step 3: Connect Linear in Craft.io
In Craft.io, open Workspace Settings
Go to Integrations and Imports
Click Connect on the Linear integration
Paste your API token
Name the connection.
Click Connect
Step 4: Select Linear teams to sync
You will now choose which Linear teams should sync with Craft.io. This step is critical:
Only selected teams will send data into Craft.io
This prevents unrelated engineering work from polluting your strategic backlog
Make sure you include all teams that might be assigned work from Craft.io
Save your selection once complete.
Step 5: Define hierarchy mapping
Next, define how work items map between the two tools.
You can choose to map:
Linear Projects to Craft.io Epics, or
Linear Projects to Craft.io Features
Once this decision is made, lower level items such as Issues are mapped automatically to maintain structural integrity.
Choose your preferred structure and save.
💡 Teams link Linear Projects to Craft.io Epics when they want a like-for-like reflection of the Linear structure, and to Craft.io Features when product managers want an additional strategic layer in Craft.io above the project to define scope, context, and prioritization.
Step 6: Field mapping overview
Craft.io automatically maps Linear’s core system fields, including:
Title
Description
Dev Status
Priority
Dev Assignee
Linear Team
Linear ID
Labels
💡 Because Linear uses a streamlined data model without custom fields, the integration automatically maps your data to its system fields for a simple, plug-and-play sync
Step 7: Initial synchronization
Click Save and then Sync to run your first import from Linear (you can also do this at a later stage).
During this step:
Items are pulled based on your selected teams
Optional filters can be applied
Team
Item Type
Label (e.g. to exclude bugs)
Imported items land in a default Product Area in Craft.io
At this point, you have a one way sync in place. You can already push confirmed items from Craft.io into Linear when they are ready.
From here, you can move items between product areas and begin slicing, prioritizing, and roadmapping.
Step 8: Configure status mapping (for bi-directional sync)
To reflect delivery progress back into Craft.io, set up status mapping:
Go to Workspace Settings
Open Workflow and Statuses
Map Linear statuses to Craft.io roadmap or workflow statuses
For example:
Linear Todo → Craft.io Ready for Dev
Linear In Progress → Craft.io In Development
This allows engineers to stay in Linear’s development centric flow while stakeholders see clear, high level progress in Craft.io.
Step 9: Set up the webhook (for bi-directional sync)
The webhook enables real time updates from Linear.
In Craft.io:
Open the Linear integration settings
Copy the unique webhook URL
In Linear
Go to Settings > API > Webhooks
Create a new webhook
Paste the Craft.io webhook URL
Select the following change events:
Issues
Issue Labels
Issue Attachments
Projects
Project Labels
Project Updates
Use the Team filter to limit events to relevant product teams
Click Create Webhook
Step 10: Verify the bi-directional sync
To confirm your two-way sync is working:
Make a change to a synced item in Linear, such as updating a title or status
Return to Craft.io
Confirm the update appears immediately
In your Craft.io integration settings, a green 'Connected' indicator confirms your bidirectional bridge is active.
What comes next?
Once the integration is live, you can:
Push prioritized items from Craft.io into Linear as part of your product workflow
Visualize delivery progress in roadmaps and dashboards
Track how Linear execution rolls up into product goals and OKRs across Workspaces and Portfolios
Need more guidance? 🙋 Our LIVE support team (at the bottom right corner of your screen) replies to ANY question!