Linear Integration

The Linear sync adapter provides full two-way synchronization between UserHero workflows and Linear teams. Push workflow items to Linear as issues, and receive status updates back through webhooks.

Prerequisites

A UserHero project on the Growth, Pro, or Pro Max plan
A Linear workspace with admin or member access
At least one workflow created in your project

Setup

1. Connect Linear

Go to your project Settings → Sync Adapters
Click Add Adapter → Linear
You'll be redirected to Linear's OAuth consent page
Authorize UserHero to access your Linear workspace
You'll be redirected back to UserHero

2. Select a Team

After authorization, choose which Linear team to sync with:

Select a team from the dropdown (shows all teams in your Linear workspace)
Click Confirm

Each sync adapter instance connects one UserHero workflow to one Linear team.

3. Configure Status Mapping

Map your workflow statuses to Linear statuses. The defaults depend on your workflow type:

Issues workflow → Linear:

UserHero Status	Linear Status
Open	Backlog
In Progress	Started
Resolved	Completed
Closed	Canceled

Tickets workflow → Linear:

UserHero Status	Linear Status
New	Backlog
Awaiting Response	Backlog
In Progress	Started
Resolved	Completed
Closed	Canceled

Leads workflow → Linear:

UserHero Status	Linear Status
New	Backlog
Contacted	Started
Qualified	Started
Proposal	Started
Won	Completed
Lost	Canceled

You can customize these mappings to match your team's Linear workflow states.

4. Priority Mapping

Priority mapping is automatic:

UserHero	Linear	Linear Value
Low	Low	4
Medium	Medium	3
High	High	2
Urgent	Urgent	1

Pushing Items to Linear

Once configured, push a workflow item to Linear:

Open a workflow item
Click Push to Linear
A Linear issue is created in the connected team
The item's detail view shows an External Reference with a direct link to the Linear issue

The created Linear issue includes:

Title from the workflow item
Description from the workflow item
Status mapped from the workflow status
Priority mapped from the workflow priority

Inbound Sync (Webhooks)

Linear sends webhook events when issues are updated. UserHero processes these to keep your workflow items in sync:

What syncs back

Linear Change	UserHero Update
Status changed	Workflow item status updated (via reverse mapping)
Priority changed	Workflow item priority updated
Assignee changed	Logged in activity

Webhook setup

The webhook is configured automatically during the OAuth setup. UserHero registers a webhook URL with Linear that listens for issue update events on the connected team.

If you disconnect and reconnect the adapter, the webhook is re-registered automatically.

Managing the Adapter

Viewing Sync Status

Each synced item shows its sync status in the detail view:

Synced — External issue exists and is linked
Sync Error — Last push or pull failed (hover for details)
Not Synced — Item hasn't been pushed yet

Disconnecting

Go to project Settings → Sync Adapters
Find the Linear adapter
Click Disconnect

Disconnecting removes the OAuth token and webhook. Existing external references on workflow items are preserved (the links still work), but no further syncing occurs.

Reconnecting

You can reconnect anytime by going through the setup flow again. If the same team is selected, existing external references will resume syncing.

Troubleshooting

Problem	Solution
Push fails with "unauthorized"	Reconnect the adapter — your OAuth token may have expired
Status not syncing back	Check that the webhook is active in Linear Settings → API → Webhooks
Wrong status mapping	Edit the adapter's status mapping in project Settings
Items created in wrong team	Check which team is selected in the adapter config

Linear