Linear

The Linear integration sends an Unhandled issue to the right Linear team as a new Linear issue, or links one your team already filed. When the Linear issue reaches a completed state, Unhandled resolves its issue automatically. It connects one Linear workspace per organization through OAuth.

Connect

You need to be an organization admin.

1. Open the organization's Integrations settings (/o/:org/settings/integrations) and click Connect next to Linear.
2. Linear asks you to authorize Unhandled with the read and write scopes.
3. Linear redirects back to the Integrations page, where Linear shows Connected with the workspace name.

The connect link carries an encrypted state that expires after 10 minutes and only completes for the admin who started it. Unhandled stores the workspace's access token encrypted. If Linear revokes it, creating, searching and linking fail until you connect again.

Map teams

Click Configure next to Linear and pick one team per project from the workspace's first 100 teams. New Linear issues created from that project land in its team. A project without a team cannot create or search Linear issues; both fail with "Map this project to a Linear team first".

Create a Linear issue

On an issue, open the menu and choose Create or link Linear issue, then Create new. The title starts as the issue title and can be edited. The description lists the exception type and message, the application (project), its environments, first and last seen times, and a View in Unhandled link back to the issue.

The dialog sets only the title. Unhandled does not set a Linear project, assignee, priority, labels or workflow state from the app yet. From an AI assistant, the link_issue tool of the MCP server can pass team to create the issue in another team, or attach an existing one by its URL or identifier. Only an organization admin can use a team other than the project's mapped one; for everyone else, creating fails with "Only an admin can use a Linear team other than the one linked to this project".

Link an existing issue

Choose Link existing to search the project's mapped team; up to 20 matches appear with their state. You can also type the issue identifier, such as SHOP-142. An issue in the mapped team works for anyone who can see the project. An issue in any other team needs an organization admin; for everyone else, linking fails with the same "Only an admin" message. The same rule applies to creating and linking through the API and the MCP server. Linking is recorded in the issue's activity, and Unlink in the same menu removes it.

Completing resolves the issue

Unhandled receives Linear's issue webhooks:

• When a linked issue moves to a completed state, Unhandled resolves the issue, if it is open or archived for a limited time, and records "resolved externally" in its activity.
• A canceled issue does not resolve anything. Moving an issue back to an open state updates the link but leaves the Unhandled issue as it is.

Sync runs one way. Resolving in Unhandled does not change the Linear issue, and Unhandled does not sync comments, assignees or priority. If the exception happens again after the issue was resolved, it regresses as usual.

Disconnect

Disconnect on the Integrations page removes the connection and its token. Team mappings and existing links are kept for when you connect again.

Self-hosting

Create an OAuth application in Linear for your Unhandled server and set:

Register https://unhandled.example.com/integrations/linear/callback as the OAuth redirect URI. Add a webhook to https://unhandled.example.com/webhooks/linear for issue events. Unhandled verifies the linear-signature header against the body and ignores every event type other than Issue.