Integrations

Connecting Linear

Import Linear issues as ProductOS features with a personal API key, keep them fresh with syncs, and mark the Linear issue done when the feature ships.

Linear connects with a personal API key. Issues import as ProductOS features (one-way, Linear → ProductOS) and re-sync on demand; the one write-back is that shipping a feature marks its Linear issue done.

What it does

Issue → Feature import. Pick a team key (or leave it empty for every team the key can read). Each issue becomes a feature with title (ENG-123: …), description, status, priority, effort (from the estimate), start and target dates, team, labels as tags, and the Linear URL and identifier under metadata.linear.
Status sync (Linear → ProductOS). Every sync re-maps the issue's workflow state onto the feature's status. Existing features are matched by Linear issue ID, so nothing duplicates.
Shipped write-back. When a feature imported from Linear is set to shipped in ProductOS, the Linear issue is moved to the team's first completed-type state. No other field is pushed back.
Import wizard. Import from Linear previews issues page by page, flags the ones already imported, and only writes the ones you tick.

There is no comment mirroring and no ProductOS widget inside Linear.

Connecting

In Linear, create a personal API key under Settings → API (read access to issues and projects is enough).
Settings → Integrations → Linear → Connect. Paste the key (lin_api_…), optionally set Team key filter (e.g. ENG) and Max pages per sync (default 4; 50 issues per page, so 200 issues per run, hard cap 10 pages), then Connect & test. The test runs Linear's viewer query and shows who the key belongs to.
Run Sync now or Import from Linear for the first pull.

Status mapping

Linear workflow states are mapped by their type, so custom state names work without configuration; there is no in-app override:

Linear state type (typical names)	ProductOS `status`
Triage	`discovery`
Backlog	`planned`
Unstarted (Todo)	`planned`
Started (In Progress, In Review)	`in-progress`
Completed (Done)	`shipped`
Canceled	`wont-do`

Estimates map to effort: 1 → xs, 2 → s, 3 → m, 5 → l, 8 and up → xl.

Priority mapping

Linear priority	ProductOS `priority`
Urgent	`critical`
High	`high`
Medium	`medium`
Low	`low`
No priority	(unset)

Conflict resolution

Linear is the authority for the fields it imports. Each sync overwrites title, description, status, priority, effort, dates, team and metadata with Linear's values, so edits you make to those fields in ProductOS are replaced on the next sync. Keep ProductOS-only context in the links along the Golden Thread (themes, feedback, initiatives, releases), which the sync never touches.

Webhook events

An inbound endpoint exists at POST /api/webhooks/linear/{workspaceId}: Linear Issue events (create and update upsert the feature, remove deletes it) are accepted after the Linear-Signature header verifies as HMAC-SHA256 of the raw body with the webhook secret, and anything else is ignored. Registering the webhook and its secret isn't exposed in Settings, so Linear sync is poll-based: changes land on the next Sync now.

Disconnecting

Settings → Integrations → Linear → Disconnect. No-op on the Linear side; in ProductOS, the imported features stay (with the Linear URL and identifier preserved under metadata.linear) but stop receiving updates. There is no bulk unlink; delete the imported features or leave them.

Golden Thread: how Linear issues fit into the upstream/downstream graph.
Webhooks reference: signature verification details.