Linear add-on mode

Added in v0.235.0 In add-on mode you keep Linear as the ticket system your team works in. orboto runs next to it for everything agents do: work sessions, claims, mandates, review, approval and the audit trail. One orboto project is linked to one Linear team, and a scope decides which Linear issues come in. You bring in the agent work, not the whole backlog.

What the link does

Work sessions, claims, mandates, review lanes, approvals and the audit trail stay in orboto. A comment someone writes in Linear reaches the agents assigned to the ticket in orboto like a comment written in orboto, however long the thread has grown. A comment deleted in Linear is removed from the orboto ticket too; a comment orboto wrote to Linear is never removed by that.

Before you start

• The orboto project carries the same key as the Linear team (for team ENG, the project key is ENG). The mirrored tickets keep their Linear keys.
• If the project already holds tickets, you confirm the merge by typing the project key when you link.
• You need the Edit project permission in orboto.
• For live updates Linear needs to reach your orboto instance over HTTPS. Without a webhook, orboto still picks up every change within 10 minutes.

Link a team

Added in v0.235.0 Open Project settings > Connectors, choose Linear and pick how orboto signs in:

• Linear sign-in (OAuth). You grant orboto access in Linear. orboto asks for read, write and admin access; admin lets it create the signed team webhook. Tokens renew themselves. Your administrator enables this option once for the instance.
• Personal API key. Create a key in Linear under Settings > API and paste it. With the key of a Linear workspace admin, orboto also creates the team webhook; with another key the link works on the 10-minute check.

Enter the team key and the scope, then start the link. orboto checks the key against the team, creates the webhook, suggests the state mapping and imports the issues your scope selects. The import uses the same Linear importer as a full move to orboto.

From the command line, the key is read from standard input only:

printf '%s' "$LINEAR_KEY" | orboto connector connect --provider linear \
  --project ENG --team ENG --scope "label:agent"

Choose the scope

Added in v0.235.0 The scope is a list of key:value terms. Terms with the same key are alternatives, different keys must all match, and an empty scope mirrors the whole team.

Example: label:agent label:bot assignee:me mirrors the issues assigned to you that carry agent or bot. An issue that enters the scope is imported; one that leaves it, or is deleted in Linear, stops syncing and its orboto ticket stays.

The scope follows Linear as it changes. Renaming a label renames it on every mirrored ticket, and deleting it removes it from all of them. When a cycle ends and the next one starts, or an issue joins or leaves a Linear project or label without being edited, orboto compares the whole scope with the mirrored issues once an hour: new members are imported, issues that dropped out stop syncing. That check is careful. If Linear answers an empty scope while issues are mirrored, for example because the scope names a label you renamed, nothing is unlinked and the link health says so. Each issue is checked again right before it stops syncing, at most 50 stop in one check, and the check keeps well inside Linear's request budget and stops early when Linear reports the hour nearly used. An issue that cannot be imported or synced is skipped and counted, so one bad issue never stops the others, and the next check tries it again.

Map the states

Added in v0.235.0 Each orboto status category (to do, in progress, in review, done, won't fix) maps to one Linear workflow state. orboto suggests the mapping from the state types of your team; change it in the Status mapping of the link. A category without a state stays in orboto.

Keep an eye on the link

Added in v0.235.0 The link card shows its health: the last webhook, the last check, write-backs waiting, failed or given up, and the reason when something needs attention. The Delivery log lists what went to Linear and what came from it; a write-back that was given up can be retried. When Linear refuses the key or the sign-in, the link stops and the project admins get a notification; replace the key or sign in again. Admin > Integrations > Add-on connectors lists every link of the workspace.

If the first import stops, for example because Linear asked orboto to slow down, the link shows the reason and Retry the initial import continues after the last page that was saved. No ticket is created twice: tickets that already exist for an issue, such as ones from an earlier import of the same Linear team, are linked instead of imported again. The retry only removes tickets the interrupted import itself wrote and nobody has touched; a ticket with a comment, time entry, status change or edit stays, and so does one someone linked to another ticket or doc or gave a sub-ticket. While the import is still writing progress the retry is refused, so it never runs against a live import. From the command line: orboto connector pull-retry --project ENG --link <id>.

Unlinking removes the webhook in Linear and stops the sync. Every mirrored ticket stays in orboto.