github-pr-reviewer

GitHub PR Reviewer Automation

Agent Canvas catalog

For new Agent Canvas installations, use the GitHub code review catalog entry. Its deterministic worker.py delegates each requested exact head to a stable conversation using the selected agent profile. It supports GitHub reviewer-request events and scheduled label scans. The manual upload flow below remains for existing deployments and is deprecated for new installations.

Create a cron automation that watches one or more GitHub repositories for pull requests with a review trigger label, starts an OpenHands review conversation once per label event, and publishes the AI review to GitHub. Windows PowerShell equivalents for the setup, packaging, upload, and API-check shell snippets are in references/windows.md.

The automation script is deterministic: PR discovery, label-event tracking, head eligibility, state persistence, stale-result suppression, the repository checkout, and its removal are all handled in Python. The LLM is invoked only for the review itself.

Before any review conversation is created, a scheduled scan evaluates the current head's GitHub-required checks, read through the GraphQL isRequired signal for the pull request. That signal is the merge policy's own source of truth and is pull-request-scoped, so it stays correct for a stacked PR whose symbolic base branch carries no branch rules of its own:

• Only checks GitHub reports as required decide the scheduled gate. An optional workflow that fails - including one that fails before creating any check run - does not block a head whose required checks pass.
• A completed required run on the exact head whose conclusion is failure, cancelled, or timed_out blocks the review. Any other unrecognized conclusion fails closed as a block rather than silently approving.
• A completed required run whose conclusion is success, neutral, or skipped does not block. A required commit status context is classified alongside required check runs.
• A queued or in_progress required run on the exact head, and a required context that has not reported a current-head check run at all, make the run exit with a waiting on checks outcome. Unfulfilled is never approval. The worker does not hold a slot polling; the next scheduled scan or explicit review request retries.
• When the required-check signal cannot be read or is empty, the gate falls back to every current-head check run and workflow run, so a red head still blocks. In that fallback, workflow runs are read as well as check runs, because a workflow can fail before creating any check run - a workflow-level error, or a pull_request run whose jobs never start. Such a run leaves a failed check suite with no check runs under it, so the commit's check-run rollup and gh pr checks both report success and only the workflow run reveals the red CI. A workflow run whose check suite already reported check runs is left to those runs, so a workflow is never counted twice.
• A scheduled scan considers the trigger label and every open PR, including drafts, that still holds an outstanding all-hands-bot review request. That is what resumes a request made while CI was running: the request is keyed by its own review_requested event, so repeated scans reuse one conversation and one review instead of creating duplicates, and a PR whose request was answered or withdrawn simply drops out of requested_reviewers.
• The scheduled scan also reviews open, non-draft PRs that nobody requested and that carry no trigger label, once their current head has no completed review by this account. That is what keeps reviewing PRs after the outstanding requests are exhausted. The delivery key is the stable scan:{repository}:{number}:{head}, so repeated scans reuse one conversation and one native review, and a changed head becomes eligible again under its new SHA.
• Each scheduled scan classifies the whole open backlog, including unrequested PRs. Blocked, pending, draft, or already-reviewed heads therefore cannot hide an eligible head behind an inspection window. The separate max_new_per_run quota limits only newly created review conversations, not the number of PRs inspected; explicit requests and trigger labels retain priority when eligible candidates are drained.
• A gate stop on an unrequested head posts no managed comment. A PR nobody asked about that is merely red or pending is simply skipped without starting an agent, which is what keeps a scan over a large backlog from posting a gate comment on every PR. The managed comment is the answer to an explicit request, so a requested or labeled head that is red or pending still gets its explanation.
• Workflow runs are read as well as check runs, because a workflow can fail before creating any check run - a workflow-level error, or a pull_request run whose jobs never start. Such a run leaves a failed check suite with no check runs under it, so the commit's check-run rollup and gh pr checks both report success and only the workflow run reveals the red CI. A workflow run whose check suite already reported check runs is left to those runs, so a workflow is never counted twice.
• Runs attributed to any other (obsolete) head SHA are ignored, so a stale failure cannot block the push that fixed it. This applies to workflow runs too.
• Only the latest run of each logical check or workflow counts. A logical check is its name plus the reporting app identity, and a logical workflow is its name plus workflow ID. The latest is chosen by the run ID (the reliable creation sequence) with the start time as a tie-break, so a re-run that fixed a check supersedes its earlier failure on the same SHA while a newer queued or in-progress re-run supersedes an earlier success and makes the head wait. Ordering by the run ID keeps a run whose start time is still absent in its true creation position in both directions.