/github-pr-reviewer

name: github-pr-reviewer
description: >
  Create an automation that reviews GitHub pull requests when a configured
  reviewer is requested or a trigger label is applied. Starts one OpenHands
  review conversation per request with the pull request's exact head checked
  out, and publishes the review to GitHub.
triggers:
  - /pr-reviewer:setup

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 th