How to set up the Linear integration
Connect Linear so your team can link issues to the journey-map steps they affect.
An Admin connects Linear once at the account level. After that, anyone in your workspace can search Linear and link issues to planning cards on any journey map.
In this guide
Set up the Linear integration
Prerequisites
Admin role at the account level. Only Admins can configure integrations, and the connection applies to the whole account.
A Linear account with permission to create a Personal API key.
Linear uses a single authentication method: a Personal API key minted from your Linear account. There is no separate Connect or OAuth flow.
Here's a quick look at the full setup before you start.
Open the Linear integration in Smaply
Go to Account Settings > Integrations and click Set up next to Linear. The Configure Linear page opens with a single empty Personal API key field and a blue help block. The form's intro mentions an organization ID, but there is no organization-ID field to fill in; the Personal API key is all you need.
Create a Personal API key in Linear
In a new tab, go to linear.app/settings/account/security and sign in. Under Personal API keys, click Create new API key, give it a name you'll recognise later (for example, smaply-connector), and click Create. Copy the generated key.
Enter the key and save
Back on the Configure Linear page, paste the key into the Personal API key field and click Save Configuration.
Confirm the connection
Smaply tests the connection and, once it succeeds, the page shows your saved key with a green confirmation. Linear is now available to everyone in your account.
Verify the setup
Reopen the Configure Linear page from Account Settings > Integrations. A connected integration shows a masked Personal API key, with a green Connection setup message reading "Successfully connected to Linear as ...". Because the key is personal, the connection runs as the Linear user who created it.
If you don't see the green confirmation, check the Troubleshooting section below.
Use Linear in planning cards
Once Linear is connected, anyone in your workspace can add a planning card to a journey map, search Linear, and link the issue it relates to. For the full flow, see How to use planning cards.
Troubleshooting
The Configure Linear page shows the integration's current state. Pick the symptom below that matches what you're seeing.
Connection Error or the connection won't save - Connection issue
The key is wrong, incomplete, or was never copied in full. Reopen Configure Linear, click Edit Configuration, and paste the key again with no extra spaces. If it still fails, create a fresh Personal API key at linear.app/settings/account/security and enter the new one.
No items found when adding a planning card - Search issue
The connection works but Linear returns nothing for your search. Check that the search text matches an issue you can open in Linear, and that the key's owner has access to that team. The connection runs with that user's Linear permissions, so issues in teams they can't see won't appear.
A connection that worked has stopped - Key revoked
A working Linear connection breaks if the Personal API key is deleted in Linear, or if the user who created it loses access to the relevant teams.
Create a new key at linear.app/settings/account/security, then reopen Configure Linear, click Edit Configuration, and paste in the new key.
Issues are missing or you can't connect at all - Permission issue
Configuring the integration needs an Admin role at the account level. If Set up or Edit Configuration isn't available, ask an account Admin to make the change.
For which Linear issues appear, the connection uses the key owner's Linear permissions. If a teammate can't find an issue you can see, the key owner may not have access to that team in Linear.
For questions about how the connection behaves across your account, such as disconnecting Linear or what happens when you remove it, see How to manage integrations.
Still not working? Contact support at help@smaply.com
Related topics
Last updated