How do I get Claude Code to ship internal refactors from tickets that live in GitHub Issues?

Tares lets you keep a project’s tickets in GitHub Issues, so the software factory for Claude Code builds your internal refactors from them into merged pull requests. Label one issue per refactor, link the repo and label to a Tares project, and write each milestone’s acceptance checks and each ticket’s working doc in Tares. The crew then takes the tickets one at a time, opens pull requests, and merges them once the reviewer passes and CI is green.

How it works

• One repo and one label pick the tickets. Every issue that carries the issue label becomes a ticket named GH-<number>, in issue number order. The label defaults to tares:<project name>.
• Status follows 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 one closed as not planned or as a duplicate is canceled.
• Order comes from GitHub. An issue that is blocked by another makes its ticket depend on that one. A blocked ticket in the crew’s project page names the tickets it waits for.
• Milestones group the refactors. GitHub milestones that the labeled issues belong to become Tares milestones. The goal starts as the GitHub milestone’s description, and you write your own goal and the acceptance checks for the milestone in Tares.
• Each ticket has a working doc. You write it in Tares, as for any ticket. It stays yours even though the ticket itself is read-only.
• The crew builds. The orchestrator hands out work and starts a builder per milestone and repo. A builder takes a ticket, works on its own branch, opens a pull request, and merges it once the reviewer passes it and CI is green.
• Tares reads, sessions write. Tares reads the repo about once a minute and never writes to GitHub. Sessions create and change issues with gh.

Set it up

1. Check that Claude Code is signed in, that gh is signed in with write access to the repos the crew works in, and that git, jq and curl are installed. Sessions that create issues use gh with the repo scope.

   gh auth login

2. Install the CLI and start Tares locally. In a second terminal, start the MCP endpoint every crew session shares. On Tares Cloud, run tares login instead and skip the MCP step.

   uv tool install tares     # or: brew install glassflow/tap/tares
   tares up
   tares mcp --transport streamable-http

3. Add a GitHub credential in Settings > GitHub that can read the repo’s issues. A fine-grained token needs Issues: read, a classic token needs the repo scope, and a GitHub App needs the Issues permission and an installation on the repo. On Tares Cloud, choose Connect GitHub instead.

4. Bring up the crew. The first run asks how far the crew may go.

   tares factory crew up

5. Plan the refactors. When you run /tares:spec, say the tickets should live in GitHub Issues and name the repo. Claude creates one issue per ticket with gh and links the project.

   tares factory spec "what you want to build"

6. To link an existing repo yourself, click Use GitHub Issues on the project’s Tickets page, pick the repo, check the label, and click Link. A connected agent can call the MCP tool instead:

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

7. Group related refactors under a GitHub milestone, and mark ordering with blocked-by links on the issues. Then write each milestone’s acceptance checks and each ticket’s working doc in Tares.

8. Hand the project to the crew when /tares:spec asks. Run tares factory crew status to see the stations and a line per project, or open the Crew page in the console.

The Get started page has the full setup, including the ticket options. The GitHub Issues connector page has the sync details.

What you get

• Refactor tickets that you manage in GitHub, with the crew’s progress mirrored back as ticket status within about a minute.
• Tickets that follow your blocked-by links and issue numbers, so related refactors arrive in the order you set.
• Pull requests that the reviewer holds to a fixed bar before anything merges.
• A project page that records each ticket with its builder, pull request and review rounds, plus the questions the crew asked you and the assumptions it made. A project, end to end follows one real project through this.
• A working doc per ticket and acceptance checks per milestone that builders read as they work.
• Events on the github_issues source for every change: ticket_created, ticket_renamed, ticket_status and ticket_removed. Triggers and agents can react to them.
• Safe failure. If a sync fails, the tickets stay as they were and nothing is canceled. An issue that loses its label becomes canceled, and its working doc stays reachable.

When something else fits

• Tickets cannot be edited in Tares when they live in GitHub. If you want to add and change them in Tares, keep them there or use Stop using GitHub on the Tickets page, which returns them with their working docs.
• The connector reads one repo and one label per project, on github.com only, with up to 1000 labeled issues and 100 milestones. GitHub Enterprise Server and GitHub Projects boards are not supported, so group tickets with GitHub milestones.
• 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.

Related