GitHub Issues: github_issues

Poll source for GitHub Issues. A project can keep its tickets in a GitHub repo instead of Tares: one repo and one issue label pick the issues, those issues become the project’s tickets, and every change made in GitHub becomes an event on the github_issues source, keyed by the ticket’s name (GH-12). Triggers and agents can react to them like any other event.

Tares only reads from GitHub. Sessions create and change the issues in GitHub itself, with gh.

Set up

1. Add a GitHub credential in Settings > GitHub. It needs 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 must be installed on the repo (an App with no installation is skipped). 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 (owner/name), check the issue label, and click Link. Or ask a connected agent to call the MCP tool link_github_issues:

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

   The issue label is optional and defaults to tares:<project name>. Tares creates the github_issues source the first time a project is linked.

3. Let sessions create the issues. The sessions that create issues use gh with the repo scope (gh auth login). When 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.

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.

What Tares keeps in sync

Tares reads the repo about once a minute. Sync now on the Tickets page reads at once.

• Tickets: every issue that carries the issue label, named GH-<number>, with its title and status. Tickets are in issue number order.

• Status, from the issue:

  issue	ticket status
  open	todo
  open, with the in progress label	in_progress
  closed as completed	done
  closed as not planned or as a duplicate	canceled

• Milestones: the GitHub milestones that the labeled issues belong to, and which tickets sit in each. Name and order come from GitHub. The goal starts as the GitHub milestone’s description, and you can write your own goal and the checks in Tares. A Tares milestone with the same name as a GitHub one becomes it. You cannot add a milestone in Tares, add it in GitHub.

• Dependencies: an issue that is blocked by another makes its ticket depend on that one.

• An issue that loses the label (or is deleted, or moves to another repo) becomes canceled in Tares rather than disappearing, so its working doc stays reachable.

The tickets are read-only in Tares. To change a title, status, milestone or dependency, change the issue in GitHub. A working doc stays yours: write it in Tares as for any ticket.

Events

One event per change, with event_type:

The payload carries change, ticket, project, repo, issue_label, the GitHub issue, and from and to for a change of value.

Provided labels

ticket (the key; GH-12), project (the Tares project), repo.

Verify

The Tickets page shows “Tickets live in GitHub” with the repo and issue label, and when it last synced. Close an issue in GitHub: within a minute the ticket moves to done, and the source’s Recent events shows the change.

When something goes wrong

• A sync fails (a revoked credential, a repo the credential can no longer see, GitHub unreachable). The Tickets page shows why, the tickets stay as they were, and nothing is canceled. Fix the cause and the next sync picks up.
• 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. Put the label back, or stop using GitHub.
• GitHub rate limits the sync. Tares waits five minutes before it tries again. If you click Sync now during that wait, the Tickets page counts down, and the API answers 429 with a Retry-After header.

Stop using GitHub Issues

Stop using GitHub on the Tickets page returns the tickets and milestones to Tares, with their working docs, and you can add and change them there again. The issues in GitHub stay as they are.

Limits

• One repo per project, and one issue label.
• github.com only. GitHub Enterprise Server is not supported.
• No GitHub Projects boards. Group tickets with GitHub milestones.
• Up to 1000 issues with the label, and 100 milestones in the repo.