This article explains how to push Epics, Features, or Stories from Craft.io into Linear, once your integration is set up. It covers when to push work, what is required, and what happens after syncing.
Before you start
To push items from Craft.io into Linear, make sure:
The Linear integration is connected and active, meaning:
Your API connection was configured by a Craft.io admin user
A Webhook was configured by a Linear admin user
A Craft.io admin has set up dev tool status automations in the Workspace settings
Craft.io admins have selected all relevant Linear teams during setup
If the integration is not yet configured, start with Setting up your Linear integration in Craft.io.
When should you push work into Linear?
Pushing an item from Craft.io into Linear represents a delivery commitment. As a best practice, items should be pushed only when:
The problem or requirement is clearly defined
Priority is agreed
Ownership is clear
The item is ready for engineering execution
Early ideas, drafts, and unvalidated requests should stay in Craft.io.
💡 This process keeps the engineering backlog clean and ensures that every technical task is rooted in a clear product requirement.
What can be synchronized between Craft.io and Linear?
Linear follows a fixed delivery structure designed to keep engineering work consistent and fast. Craft.io is more flexible, allowing teams to shape, organize, and prioritize work in ways that suit their product and stakeholders.
The integration bridges these two approaches by mapping Craft.io’s flexible planning structure onto Linear’s delivery model.
When you push an item from Craft.io into Linear, the corresponding delivery item is created automatically based on your chosen hierarchy.
For example:
If Epics are mapped to Projects, pushing a Craft.io Epic creates a Linear Project
If Features are mapped to Issues, pushing a Craft.io Feature creates a Linear Issue
If Stories are mapped to Sub Issues, pushing a Craft.io Story creates a Linear Sub Issue
Lower level items are always created beneath their parent. This preserves structure and context for engineering teams, while allowing product teams to keep planning flexible in Craft.io.
Step 1: Assign a Linear team
Before syncing from Craft.io to Linear, make sure the item is assigned to a Linear Team in Craft.io.
This step is mandatory.
Linear Projects, Issues and Sub Issues cannot exist without a team
If no Linear team is selected in Craft.io, the sync cannot be initiated
To push an item from Craft.io into Linear:
Open the Epic, Feature, or Story in Craft.io
Review the Item Properties panel on the right
Assign the relevant team in the 'Linear Team' dropdown
Click Sync
Craft.io will now create the corresponding Project, Issue or Sub Issue in Linear.
💡 Linear Projects can have multiple Teams assigned, whilst Issues can only have a single Team assigned. Make sure this is reflected in your selection in Craft.io, to ensure team alignment when pushing work into Linear.
Step 2: What happens after the first sync
After an item is synced for the first time:
The item remains connected between Craft.io and Linear
Changes to synced fields stay aligned across both tools
Delivery progress becomes visible in Craft.io roadmaps and dashboards
Linear becomes the source of truth for execution activity, while Craft.io remains the source of truth for planning and prioritization.
💡 Once an item is pushed to Linear, a Linear ID and link will appear. Add these as columns into your table/backlog view to see the details.
Step 3: Updating synced items
After syncing, you can continue to update items in Craft.io.
Use Craft.io to update problem context, descriptions, and priority
Use Linear to manage task breakdown, delivery status, and execution
If an item is synchronized between Craft.io and Linear, any Linear status updates will overwrite statuses in Craft.io (if the Webhook and dev status automations are in place). Craft.io statuses cannot overwrite Linear statuses, regardless of whether the sync is one-way or bidirectional.
💡 If an item is deleted in Craft.io, a synchronized item is not be deleted in Linear (and vice versa). In such a scenario, the connection is simply severed, and both items will remain active, but disconnected from one another.
Common issues and how to resolve them
Item titles, descriptions, labels and priorities updated in Linear are not flowing back to Craft.io
Make sure the Linear Webhook is in place, with sufficient permissions. Without this, updates to fields in Linear won't trigger an update in Craft.io
Items fail to sync or only partially sync
Ensure the Linear API key has sufficient access (Read and Write at minimum), for all relevant Linear teams. A Linear Admin user will be able to confirm this.
Changing a status in Linear does not update the status in Craft.io
Make sure Linear statuses are mapped to Craft.io statuses in your Workspace settings. Without this, status updates won't flow back into Craft.io.
An item isn't updated, or an error message appears
Use the 're-sync' button to align the most recent updates from Craft.io into Linear
What’s next
Now that you’re able to push work from Craft.io into Linear, you can:
Track real time delivery progress in Craft.io using Linear status data
Visualize execution across teams with roadmaps and progress dashboards
Understand how Linear delivery connects to product goals and OKRs
Close the loop with stakeholders and customers using connected feedback
Need more guidance? 🙋 Our LIVE support team (at the bottom right corner of your screen) replies to ANY question!