Linear

Linear connects with a single personal API key — no URL to configure — and feeds your assigned issues into the Inbox, images included. Like the other trackers it’s issues-only: workspaces launched from Linear tasks ask you to pick the repository.

Creating the API key

Click Create an API key on Linear ↗ in the connect form. It opens https://linear.app/settings/account/security — in Linear, that’s Settings → Security & access, where personal API keys live.

Birch needs a personal API key, not an OAuth token. The key reads and updates issues as you, so no extra scope configuration is involved.

Adding the account

1. Open Settings → Integrations (⌘, / Ctrl+,) and click the Linear tile.
2. Paste the key into the single field — Personal API key (Linear → Settings → Security & access). There is no URL field: Linear is cloud-only, so there is nothing to point Birch at.
3. Click Verify & connect. Birch verifies the key before storing it; on success the account appears with a Connected badge and Sync now / Remove buttons.

The key is stored in the system keychain, and multiple Linear accounts can be connected. See the providers overview for the shared connection model.

What you get

• Assigned issues in the Inbox Tasks tab, synced roughly every 10 minutes, labeled by their Linear identifiers (ENG-123) — see the Inbox overview.
• Embedded images. Images in an issue’s description are downloaded as thumbnails and handed to the agent when a workspace launches from the task. Linear’s uploads are private, so Birch fetches them with the same API key that read the issue — no extra setup.
• Hierarchy. Sub-issues carry their parent’s identifier and nest under it in the Inbox list.

No PRs, no repository matching

Linear has no pull requests and no git remote, so clicking Start workspace on a Linear task opens the Choose Repository dialog — pick where the work should happen. That’s the designed flow. See Start a workspace from a task.

Status transitions

When you start a workspace from a Linear task, or create a PR from that workspace, Birch offers to move the issue to another workflow state (Todo, In Progress, and so on — whatever your workflow defines).

Configure the behavior per account in Settings → Tasks: Ask each time, Change automatically (after a status has been remembered), or Never offer — see status transitions.

Troubleshooting

• Key refused on verify — make sure it’s a personal API key from Settings → Security & access. Tokens minted through an OAuth application are a different credential and won’t work here.
• Rate limiting — Linear throttles API usage per key. Birch recognizes Linear’s rate-limit responses and treats them as temporary: the affected sync fails quietly and the next ~10-minute cycle retries.