GitHub Issues, Projects & pull requests

One app install, three different boards — issues, a Projects board, and a pull request inbox.

GitHub connects through the Peractor GitHub App. An admin installs it once on the account or organization. Peractor stores no long-lived tokens: the app mints short-lived, repository-scoped credentials on demand.

The same install powers three separate trackers, because GitHub has three genuinely different task models. Each is its own decision, with its own routing and its own auto-run switch.

GitHub Issues

• What you connect: a repository. Every open issue becomes a task; closed or transferred issues leave the backlog.
• Statuses are honest. GitHub issues are open or closed, so that is the model — Open and Closed, nothing invented. The panel is a flat list, not a fake board. Labels sync too, as routing inputs rather than statuses.
• Sync is instant — the app's webhook delivers issue events as they happen, with the 30-second poll as a backstop.
• Peractor's outbound status write opens or closes the issue; comments post as the app. Published artifacts arrive as links, since GitHub has no comment-attachment API.
• A connected repository also fills in the project's repository if it does not have one.

GitHub Projects

• What you connect: an organization-owned Project board. Every item syncs in, whatever its status.
• Real statuses. The board's Status field becomes the task's status vocabulary, in board order, with colours. Workflow automation can move items between them.
• Comments go to the item's underlying issue; draft items have none. Sync is by poll.
• Requires the app to have Organization Projects read and write. If the grant is missing, the settings page shows a re-connect warning.

Pull requests

The third tracker turns incoming pull requests into tasks, so an agent can review them and you can see where each one stands. A pull request with a status, a history of runs, and a place someone can look at it.

• What you connect: a repository. Every open pull request becomes a task.
• Six statuses, not two — Draft, Open, Changes requested, Approved, Merged, Closed. The two that matter most to a reviewer do not exist on an issue at all.
• Write-back is deliberately partial. Moving a card can close, convert to draft, reopen, or mark ready. It refuses Approved, Changes requested, and Merged, with a message saying so: the first two are a person's judgment, and the third would merge somebody's code because a card moved.

A review run reads, and writes nothing

A run started from a pull request task is a different shape from every other run:

• It cuts no branch of its own. It checks out the pull request's head as a detached ref, which is the one name that resolves for pull requests from forks as well as from the repository itself.
• It diffs against that pull request's own base, which is not always the default branch — a stacked pull request targets the one below it.
• The agent is told it is reviewing, and who wrote the code. Without that framing it would read the description as "build this".
• It writes nothing to the repository: no commit, no push. A git step logs a warning saying it has no branch to act on rather than skipping silently.

What the review produces reaches the pull request as a comment, the way every tracker's outbound sync reaches its issue.

Removing the app

Because the app is installed on GitHub's side, removing it happens there too — GitHub's settings, not Peractor's. Disconnecting individual repositories or boards works in Peractor as usual.

The app is also the recommended push credential: the same install lets runs push branches and open and merge pull requests with per-run, per-repository tokens.