Skip to Content

Where do I see progress on docs updates when the tickets live in a Linear project?

Tares shows docs update progress on the project page, where each Linear ticket appears with the builder that held it, its pull request and its review rounds. The ticket stays in Linear and the sessions update it with their own tools. Tares only reads Linear, about once a minute, and the Tickets page shows when it last synced.

How it works

A project can keep its tickets in a Linear project instead of Tares. Each Linear issue becomes a ticket of the project, and Tares creates the linear source the first time you link a project. The Linear connector polls and keeps these in sync:

  • Title, status, order and identifier, such as ENG-123, about once a minute.
  • Status from the issue’s workflow state. Backlog, unstarted and triage show as todo, started as in_progress, completed as done, and canceled and duplicate as canceled.
  • The Linear project’s milestones and which tickets belong to each.
  • Dependencies. An issue that blocks another makes the blocked ticket depend on it.

Every change in Linear also becomes an event on the linear source, such as ticket_created, ticket_renamed, ticket_status, ticket_reordered and ticket_removed. Triggers and agents can react to these events like any other.

The sessions create and change tickets in Linear with their own tools. Tares never writes to Linear. An issue that leaves the Linear project becomes canceled in Tares instead of disappearing, so its working doc stays reachable.

The project page that the crew builds for each project brings the ticket together with the rest of the record. The Tickets fold shows each ticket with the builder that held it, its pull request and its review rounds. Across the top, four steps (Spec, Build, Review and Done) and a progress bar with one segment per ticket show how far the project has come.

Set it up

  1. Connect Linear in Settings > 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. Link the project. On the project’s Tickets page, click Use a Linear project and pick the one that holds your docs update issues. A project that already has tickets of its own cannot be linked.

  3. Hand the project to the crew. Bring up the crew and plan the project. The crew setup is on Get started.

    tares factory crew up
tares factory spec "what you want to build"

  4. Open the project page from the Crew page in the console, at http://127.0.0.1:8787/crew on a local Tares. Open the Tickets fold to see each docs ticket with its builder, pull request and review rounds.

  5. Check the sync. The Tickets page says “Tickets live in Linear project” and shows when it last synced. Click Sync now to read at once. Change an issue in Linear, and within a minute the ticket follows and the source’s Recent events shows the change.

What you get

  • One place to follow a docs update. The Linear ticket keeps its identifier, and the project page adds the pull request and the review rounds next to it.
  • A state for every ticket on the project page: to do, in progress, in review, merged or blocked. A blocked ticket names the tickets it waits for.
  • Review history you can read. In the worked example, most tickets passed on the first round and two needed a second, where the reviewer asked for changes and the builder made them.
  • The docs the sessions build from, in the Docs fold. It holds the starting prompt, the spec, the plan, the project’s AGENTS.md and the project’s memory, plus the AGENTS.md and memory shared by every project. All docs lists each with its kind, size and who changed it last, and you can edit any of them there.
  • A working doc for each ticket, kept with the ticket.
  • A standup report, opened with Standup on the Crew page. It lists what is done, started, in review, blocked and waiting on you, with pull request links, for each project handed to the crew.
  • A clear error when a sync fails. A revoked key or a Linear project the connection can no longer see is named on the Tickets page, and the tickets stay as they were. Connect again in Settings > Linear to fix it.

For a full walk through the project page, see A project, end to end.

When something else fits

  • If you want Tares to hold the tickets itself, skip the Linear link and keep them as Tares tickets. Stop using Linear on the Tickets page keeps the tickets you already have as Tares tickets.
  • If your tickets are GitHub issues, link the repo instead. The GitHub Issues connector works the same way, as a read-only source.
  • If you need to change a ticket from Tares, do it in Linear. Tares reads the ticket and does not write to it.

Still stuck? Get help

Last updated on