How do I connect Linear so a project’s tickets are read from a Linear project?

Tares reads a project’s tickets from a Linear project once you connect Linear in Settings > Linear and click Use a Linear project on the project’s Tickets page. On Tares Cloud you approve the Tares app, and on your own Tares you paste a personal API key with read access. Tares creates the linear source the first time you link a project, and a project that already has tickets of its own cannot be linked.

How it works

The Linear connector is a poll source. One Linear connection serves the whole workspace, and each project you link keeps its tickets in a Linear project instead of Tares.

• The issues in the Linear project become the project’s tickets, keyed by the issue identifier, for example ENG-123.
• Tares reads about once a minute. Sync now on the Tickets page reads at once.
• Every change made in Linear becomes an event on the linear source, so triggers and agents can react to it like any other event.
• Tares only reads from Linear. Sessions create and change tickets in Linear itself.

What Tares keeps in sync:

• Ticket title, status, order and identifier.
• Status, mapped from the issue’s workflow state. Backlog, unstarted and triage are todo. Started is in_progress. Completed is done. Canceled and duplicate are canceled.
• Milestones of the Linear project and which tickets belong to each.
• Dependencies. An issue that blocks another makes the blocked ticket depend on it.
• An issue that leaves the Linear project (moved, deleted or archived) becomes canceled in Tares rather than disappearing, so its working doc stays reachable.

Set it up

1. Open Settings > Linear in Tares and connect Linear.
   • On Tares Cloud, click Connect Linear and approve the Tares app in Linear.
   • On your own Tares, create a personal API key in Linear under Settings, Security and access, Personal API keys, and paste it into Tares. Read access is enough.
2. Open the project’s Tickets page and click Use a Linear project.
3. Pick the Linear project. Its issues become the project’s tickets, and Tares creates the linear source the first time a project is linked. You do not add this source by hand.
4. Check the result. The Tickets page shows “Tickets live in Linear project …” and when it last synced.
5. Change an issue in Linear. Within a minute the ticket follows, and the source’s Recent events shows the change.

If the project already has tickets of its own, it cannot be linked.

On your own Tares, start Tares first so you can reach Settings:

tares up

Each change arrives as one event with an event_type:

• ticket_created: an issue was added to the Linear project.
• ticket_renamed: its title changed.
• ticket_status: it moved to a status that maps to a different Tares status.
• ticket_reordered: its order changed.
• ticket_removed: it left the Linear project.

What you get

• A project whose tickets mirror a Linear project, with title, status, order, identifier, milestones and dependencies kept current about once a minute.
• One event per change on the linear source, with a payload that carries change, ticket, project, linear_project, the Linear issue, and from and to for a change of value.
• Three labels you can use in triggers and filters: ticket (the issue identifier), project (the Tares project) and linear_project.
• Clear failure feedback. When a sync fails, for example because of a revoked key or a Linear project the connection can no longer see, the Tickets page says why and the tickets stay as they were. Connect again in Settings > Linear to recover.
• A way out. Stop using Linear on the Tickets page keeps the tickets as Tares tickets.

When something else fits

• If the project already has tickets in Tares, you cannot link it to a Linear project. Use a project without tickets of its own.
• If you want Tares to write to Linear, it does not. Sessions update Linear with their own tools, and Tares only reads the tickets.

Related