Skip to Content

Where do I see progress on internal refactors when the tickets live in GitHub Issues?

Tares shows progress on your internal refactors on the project page, where each GitHub Issues ticket appears with its pull request and its review rounds. The ticket stays in GitHub and the sessions update it there with their own tools, while Tares reads it. A progress bar on the page has one segment per ticket, so you see how far the refactor has come at a glance.

How it works

Your refactor tickets stay in your tracker. You link a project to one GitHub repo and one issue label, and every issue with that label becomes a ticket of the project, named GH-12 for issue 12.

  • Tares reads, sessions write. Tares only reads from GitHub, about once a minute. The sessions create and change the issues in GitHub itself, with gh.
  • Status comes from the issue. An open issue is todo, an open issue with the in progress label is in_progress, an issue closed as completed is done, and an issue closed as not planned or as a duplicate is canceled.
  • Milestones and dependencies follow GitHub. The GitHub milestones that the labeled issues belong to show up as milestones, and an issue blocked by another makes its ticket depend on that one.
  • Every change is an event. The github_issues source records ticket_created, ticket_renamed, ticket_status and ticket_removed, so triggers and agents can react to them like any other event.
  • The project page ties it together. The Tickets fold lists milestones with their acceptance checks, and each ticket with the builder that held it, its pull request and its review rounds. A blocked ticket names the tickets it waits for. Details of the connector are on the GitHub Issues connector page.

Set it up

These steps follow the order of the Get started guide for a local Tares. On Tares Cloud, run tares login instead of starting Tares and the MCP endpoint yourself.

  1. Add a GitHub credential in Settings > GitHub. It must be able to read the repo’s issues. A fine-grained token needs the repo with Issues: read, a classic token needs the repo scope, and a GitHub App needs the Issues permission and an installation on the repo.
  2. Sign in to gh with write access to the repo, because the sessions create and update the issues with it.
  3. Start Tares and the crew. Run these in order, with tares mcp in a second terminal:
gh auth login
tares up
tares mcp --transport streamable-http
tares factory crew up
tares factory spec "what you want to build"
  1. Say where the tickets live. When you plan the project and say the tickets should live in GitHub Issues, Claude creates them with gh and links the project.
  2. Or link an existing project by hand. On the project’s Tickets page, click Use GitHub Issues, pick the repo (owner/name), check the issue label and click Link. A connected agent can call the MCP tool instead:
link_github_issues(repo="acme/shop", issue_label="tares:shop")

The issue label is optional and defaults to tares: followed by the project name. Use a label such as the one above to pick out your refactor issues. Tares creates the github_issues source the first time a project is linked.

  1. Verify. The Tickets page shows “Tickets live in GitHub” with the repo, the issue label and the time of the last sync. Close an issue in GitHub and within a minute its ticket moves to done. The source’s Recent events shows the change. Sync now reads at once.

What you get

  • One page per project that records the whole refactor. Across the top are four steps, Spec, Build, Review and Done, with a progress bar of one segment per ticket.
  • For each ticket, its state (to do, in progress, in review, merged or blocked), the builder that held it, its pull request and how many review rounds it took. A ticket that needed changes shows the second round that passed.
  • The GitHub fold lists the repos the project changes, where each is checked out and its open and merged pull requests.
  • The Decisions fold holds every question the crew asked you, with your answer. The Assumptions fold holds every choice the crew made on its own, and whether you kept it.
  • The Crew page, at http://127.0.0.1:8787/crew locally, shows who is working on what, plus a Standup report of what is done, started, in review, blocked and waiting on you.
  • Tickets stay in your tracker, so your team keeps using GitHub Issues as before. An issue that loses the label becomes canceled in Tares instead of disappearing, so its working doc stays reachable.

For a full walk through one project, from spec to merged pull requests, read A project, end to end.

When something else fits

  • The tickets are read-only in Tares. To change a title, status, milestone or dependency, change the issue in GitHub. If you want to edit tickets in Tares, use Stop using GitHub on the Tickets page, which returns them to Tares and leaves the GitHub issues as they are.
  • A project that already has tickets of its own, or keeps them in Linear, cannot be linked to GitHub Issues. Use the Linear connector for Linear.
  • Limits: one repo and one issue label per project, github.com only, no GitHub Projects boards (group tickets with GitHub milestones), up to 1000 labeled issues and 100 milestones.

Still stuck? Get help

Last updated on