Skip to main content
Connect Linear once. From then on your issues appear in Orchestra and stay current (new issues, edits, status changes, reassignments) without anyone running a command. A synced issue is a real Orchestra work item. It carries its Linear key as its ref, keeps a link back to Linear, and lands already connected to the sessions and commits that mention it, because Orchestra has been recording those references all along.
A copy you can change. Synced issues and projects are copies inside Orchestra. Change their status, assignee, priority, title or project, comment on them, move issues between projects, rename or archive a project, or delete any of them, all from Orchestra. Nothing is written back to Linear: your changes stay in Orchestra, and Linear keeps its own.

​
Your changes win

When Linear syncs an item again, Orchestra keeps every field you changed here exactly as you set it, and keeps updating every field nobody touched. Rename an issue here and later rename it in Linear: Orchestra keeps your name. Leave its description alone and edit it in Linear: Orchestra follows Linear. Deleting works the same way. Delete a synced issue or project in Orchestra and it stays deleted, even though it still exists in Linear and Linear keeps syncing it. A deleted project’s issues stay, in no project.

​
Connect

The usual way is Settings, Integrations in the app, or the Linear step of workspace setup: choose Connect Linear, and approve on Linear’s own screen. Orchestra asks Linear for one thing, read access, which it uses to read your teams, issues, projects and comments. It never creates, edits or deletes anything in Linear. Every public team in your Linear workspace is synced. The authorization belongs to the workspace, not to one person’s API key: it keeps working when the person who connected it leaves. Orchestra keeps it encrypted on the server and renews it as Linear requires; it is never sent to your browser. Disconnecting gives it back to Linear. The page then shows which Linear workspace you are connected to, the last sync, any error, and whether live updates are on, with Resync to pull again right away.
Connected with an API key before? That connection keeps working exactly as it did. Settings offers Switch to Linear sign-in: approving on Linear replaces the stored key with the workspace’s authorization and removes the webhook the key registered. Nothing already synced changes.
From a terminal, for headless setups and scripting, a key still works:
That is the whole setup. It validates your API key against Linear, stores it encrypted, runs a first full sync, and hands the job to the background watcher.
  • --team is your Linear team key (the ENG in ENG-123). Without it, every team the key can see that is not private is synced.
  • --key lin_api_… passes the credential explicitly. Without it, Orchestra reads LINEAR_API_KEY from the environment. Create a key at linear.app/settings/api.

​
Then nothing

After connecting, Orchestra syncs every few minutes by itself. There is no command to run and no job to schedule.

​
Check it is working

A healthy integration reads like this:
A broken one says so plainly, which is the point:
Orchestra treats a silently dead integration as the failure worth engineering against. After repeated failures it stops calling Linear, backs off exponentially, and surfaces the error rather than retrying forever in silence. A revoked key trips that immediately instead of after five attempts, because a revoked key is never going to start working on its own.

​
Private teams are never synced

A synced issue is visible to everyone in your Orchestra workspace. An issue in a private Linear team is visible only to that team’s members. So Orchestra never syncs a private team: naming one with --team is refused, a workspace-wide connection skips them, and Settings lists the teams it left alone so the gap is visible rather than silent.

​
Live updates

When you connect, Orchestra registers a Linear webhook for your public teams, signed with a secret it keeps encrypted beside your API key. Changes then arrive in seconds: issues, comments, projects and labels.
  • Every delivery is checked against that secret, over the exact bytes Linear sent. A delivery older than a minute is refused as a possible replay.
  • A delivery is treated as a signal, not as data: Orchestra fetches the issue or project from Linear and writes it exactly as a scheduled pull would. A late or repeated delivery therefore applies the current state, and changes nothing the second time.
  • Registering a webhook needs admin rights in Linear. A connection made on Linear’s screen asks only to read, so its live updates are off, Settings says so, and changes arrive with the sync every few minutes. With an ordinary key, live updates stay off too, Settings says why, and the scheduled sync still keeps everything current within a few minutes.
  • Disconnecting removes the webhook from Linear.
The webhook address is shown in Settings.

​
What syncs

What does not sync: attachments, sub-issues, relations, cycles, estimates, and issue history. Nothing is written back to Linear, except registering the webhook when you connect: changes you make here stay in Orchestra.

​
Rate limits

When Linear says to slow down, Orchestra waits exactly as long as Linear asked before calling again, and deliveries that arrive meanwhile are caught up by the next pull.

​
Status mapping

Linear’s workflow state types map onto Orchestra’s fixed set: Canceled issues land in done because Orchestra has no terminal-but-unfinished status yet. The real Linear state name travels with the item, so a canceled issue still reads “Canceled” rather than claiming it was completed. If your team’s workflow needs different treatment, a per-connection override map keyed on the Linear state name takes precedence over this table.

​
Assignees

When a Linear user’s email matches a known Orchestra identity, the item is assigned to that person and the link is remembered, so later syncs match directly. When no one matches, the item stays unassigned and records the Linear display name. Orchestra does not invent people who have never used it: that would quietly fill your People list with strangers.

​
Two refs, no migration

Orchestra items created natively get refs like W-7. Synced issues keep their tracker key: ENG-123. Both live in the same list, and neither is converted into the other. The native prefix is one letter on purpose. Orchestra’s ticket-key extractor requires at least two leading characters, so W-7 in a commit message can never be mistaken for a tracker issue, while ENG-123 is recognized, which is exactly what links your existing sessions and commits to a synced issue the moment it arrives.

​
Disconnecting

In Settings, Integrations, choose Disconnect. Syncing and live updates stop, and Orchestra deletes its authorization or key. Issues already synced stay as items: disconnecting does not delete your team’s work. Keys and authorizations are stored encrypted, are never written to Orchestra’s history, and are never shown again after you save them.

​
Syncing again now

Resync in Settings pulls right away. From a terminal:
Running it is harmless at any time: it ends at the same result as the scheduled sync.