How do Linear workflow states map to ticket statuses in Tares?

Tares maps each Linear workflow state to one of four ticket statuses. Backlog, unstarted and triage become todo, started becomes in_progress, completed becomes done, and canceled and duplicate become canceled. Tickets sync about once a minute, and Sync now reads at once.

How it works

When you link a Linear project to a Tares project, the issues become the project’s tickets. Tares reads each issue’s workflow state and sets the ticket status from it. The mapping is fixed:

The Linear connector is a poll source. It syncs the title, status, order and identifier of each ticket about once a minute. Tares only reads from Linear, so sessions create and change tickets in Linear itself.

Every change becomes an event on the linear source, keyed by the issue identifier such as ENG-123. A move to a state that maps to a different Tares status produces a ticket_status event. Moving an issue between two states that share a status, for example backlog to unstarted, does not change the Tares status, so it produces no ticket_status event.

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. In Settings > Linear, connect Linear. One connection serves the whole workspace.
   • On Tares Cloud, click Connect Linear and approve the Tares app in Linear.
   • On your own Tares, paste a personal API key from Linear (Settings, Security and access, Personal API keys). Read access is enough.
2. Open the project’s Tickets page, click Use a Linear project and pick one. Tares creates the linear source the first time you link a project. A project that already has tickets of its own cannot be linked.
3. Change an issue’s state in Linear. Within about a minute the ticket status follows the mapping above. To see it at once, click Sync now on the Tickets page.
4. Check the result. The Tickets page shows “Tickets live in Linear project …” and when it last synced, and the source’s Recent events shows the change.

To react to status changes, filter on the event type of the linear source in a trigger. This uses keys that Tares triggers already have:

- name: pr-merged
  sources: [github]
  filters:
    - { field: event_type, op: eq, value: pull_request }
  cooldown: 5m

Replace the source and the filter value with linear and ticket_status for Linear status changes.

What you get

• Ticket statuses in Tares that follow Linear workflow states without any manual mapping.
• Three Linear states (backlog, unstarted, triage) collapsed into one todo status, and two (canceled, duplicate) into one canceled status.
• Events you can use in triggers and agents: ticket_created, ticket_renamed, ticket_status, ticket_reordered and ticket_removed. The payload carries change, ticket, project, linear_project, the Linear issue, and from and to for a change of value.
• Labels ticket (the issue identifier), project and linear_project on each event.
• Milestones and dependencies synced too. An issue that blocks another makes the blocked ticket depend on it.
• Clear failure handling. When a sync fails, for example after a revoked key, the Tickets page says why and the tickets stay as they were. Connect again in Settings > Linear to recover.

When something else fits

• If you want Tares to hold the tickets itself, leave the project without a Linear link. To go back, click Stop using Linear on the Tickets page, which keeps the tickets as Tares tickets.
• If you need a project that already has Tares tickets to use Linear, note that it cannot be linked.
• If you want tickets from a GitHub repo instead, use the GitHub Issues source.

Related