How does a GitHub issue’s state map to the ticket status in Tares?

Tares maps each GitHub issue to a ticket status: open is todo, open with the in progress label is in_progress, closed as completed is done, and closed as not planned or as a duplicate is canceled. An issue that loses the label, is deleted or moves to another repo also becomes canceled instead of disappearing. Tares reads the repo about once a minute, so a change in GitHub shows up in the ticket within a minute.

How it works

The github_issues source is a poll source. A project keeps its tickets in one GitHub repo, and one issue label picks which issues count. Every issue that carries the label becomes a ticket named GH-12 for issue 12, with its title and status. Tickets are in issue number order.

The status comes from the issue:

Three other cases also end in canceled:

• The issue loses the label.
• The issue is deleted.
• The issue moves to another repo.

The ticket stays in Tares as canceled, so its working doc stays reachable.

Every change becomes an event on the source, keyed by the ticket name. The event_type tells you what happened:

• ticket_created: an issue got the label.
• ticket_renamed: its title changed.
• ticket_status: it moved to a status that maps to a different Tares status.
• ticket_removed: it no longer carries the label.

The payload carries change, ticket, project, repo, issue_label, the GitHub issue, and from and to when a value changes. Triggers and agents can react to these events like any other event, as described in AI SRE.

Set it up

1. Add a GitHub credential in Settings > GitHub. A fine-grained token needs the repo with Issues: read. A classic token needs the repo scope. A GitHub App needs the Issues permission and must be installed on the repo. Tares tries the stored credentials one after another until one can read the repo, so an existing GitHub connector credential works.
2. Link a project. On the project’s Tickets page, click Use GitHub Issues, pick or type the repo as owner/name, check the issue label, and click Link. The label is optional and defaults to tares: followed by the project name. Tares creates the github_issues source the first time you link a project.
3. Or ask a connected agent to call the MCP tool link_github_issues:

link_github_issues(repo="acme/shop", issue_label="tares:shop")

4. Let sessions create the issues. Sessions use gh with the repo scope. If you plan a project with /tares:spec and say the tickets should live in GitHub Issues, Claude creates them with gh and links the project.
5. Verify the mapping. The Tickets page shows “Tickets live in GitHub” with the repo, the issue label and the last sync time. Close an issue in GitHub and the ticket moves to done within a minute. The source’s Recent events shows the change. Sync now reads at once.

A project that already has tickets of its own, or that keeps them in Linear, cannot be linked. A repo and issue label belong to one project. The full details are on the GitHub Issues connector page.

What you get

• Ticket statuses in Tares that follow your issues without manual updates.
• Closed issues sorted correctly: completed work shows as done, and work closed as not planned or as a duplicate shows as canceled.
• No vanishing tickets. An issue that loses the label, is deleted or moves to another repo becomes canceled, and its working doc stays reachable.
• Milestones taken from the GitHub milestones of the labeled issues, and dependencies taken from issues that are blocked by another.
• One event per change, so triggers and agents can act on a status move.
• A safe failure mode. If a sync fails, for example because of a revoked credential or an unreachable GitHub, the tickets stay as they were and nothing is canceled. If no issue carries the label any more while tickets are still open, Tares stops with an error that asks whether the label was renamed, and cancels nothing. If GitHub rate limits the sync, Tares waits five minutes before it tries again.

When something else fits

• Tickets are read-only in Tares. To change a title, status, milestone or dependency, change the issue in GitHub. A working doc stays yours to write in Tares.
• If you want to edit tickets in Tares, click Stop using GitHub on the Tickets page. The tickets and milestones return to Tares with their working docs, and the issues in GitHub stay as they are.
• The connector supports one repo and one issue label per project, github.com only, up to 1000 labeled issues and 100 milestones. GitHub Projects boards are not read, so group tickets with GitHub milestones.

Related