# PR watcher

> **GitHub & GitLab.** The PR watcher works on both forges. On GitLab it watches
> **merge requests**: it posts the verify result as an MR note and, on Max,
> approves (where approvals are available) and merges the MR.

AM watches the **open pull requests / merge requests** on your repo — including
external contributors' — checks each one against your
[Verification Gate](/docs/verification-gate), and posts the result as a PR comment
(an MR note on GitLab). On Max it can also approve and merge a PR/MR that passes.

## Enable it

In **Repo settings → PR watcher** (Pro plan or higher):

- **PR watching** — toggle on.
- **Watch policy** (optional JSON) — filter which PRs to act on by `authors`,
  `labels`, or `target_branch`.

Set a [verify command](/docs/verification-gate) — that's the gate run against each
PR's code.

## How it works

1. **Sync** — AM pulls open PRs from GitHub into a candidate queue (scored;
   draft/policy‑filtered). AM's *own* PRs (the `am/…` branches it opens) are
   excluded — this is for the PRs **you** receive.
2. **Verify** — for the top candidate, a worker checks out that PR's code (via the
   `pull/N/head` ref, so **fork PRs work too**), runs your `verify_cmd`, and
   reports pass/fail. The worker only **reads** the PR — it never commits or pushes.
3. **Comment** — the panel posts the result on the PR:
   *✅/❌ automaintainer verify gate: passed/failed* (with output). **Pro+**.
4. **Approve & merge** — on **Max+**, a passing PR also gets a GitHub approval
   review, and is merged if the repo has auto‑merge on.

## Manual control

- `POST /api/repos/{id}/pr-candidates` — sync open PRs.
- `GET /api/repos/{id}/pr-candidates` — list candidates.
- `POST /api/pr-candidates/{id}/verify` — verify one now.
- `POST /api/pr-candidates/{id}/reject` — skip one.

## Pick a PR to review

You don't have to enable continuous watching to verify one specific PR. In
**Repo settings → Automation**, switch the mode to **PR watch** and the
**PR candidates** panel appears: click **Sync PRs**, then **Review this** on the
PR you want. AM verifies that PR against the gate on the next scheduler cycle
(~2 min) — the manual equivalent of issue solving's "Solve this". The pin is
one-shot: it clears itself once dispatched, and continuous watching does not need
to be on.

Drive it from automation with `POST /api/repos/{id}/review-pr/{pr_number}` (the
PR must already be a synced candidate). Plan-gated to Pro+, like PR watch.

## Pick a PR to solve

Next to **Review this**, each PR candidate also has **Solve this** (#275) — the PR
equivalent of "pick an issue to solve". Where *Review* is a read-only gate check,
*Solve* has AM **do the work**: it checks out the PR's branch, continues from its
commits, makes it merge-ready (finishes unfinished work, fixes failing checks,
addresses review feedback), and **pushes back to that branch — updating the PR**
rather than opening a new one (reuses the [resume-branch](/docs/recovering-a-pr)
path). A run starts immediately and opens in the run view.

This works for PRs on branches AM can push to — its own `am/*` branches or
same-repo branches. External-fork PRs can't be pushed to, so they'll fail at the
push step. Automation: `POST /api/repos/{id}/solve-pr/{pr_number}`.

## Security note (read this)

PR watching **runs untrusted contributor code through your verify gate on your
worker** (which holds your provider keys + GitHub token). Only enable it on repos
whose contributors you trust, or use the watch policy to restrict to known
authors. A malicious PR could try to exfiltrate via the verify command or test
code — the same caveat applies to any CI that runs PR code.

## Gotchas

- **Needs a GitHub token** (for fetching PRs + posting comments/approvals).
- GitHub won't let you **approve your own PRs** — so on PRs authored by your own
  account, AM comments but the approval is skipped (works normally for external
  authors).
- Approve/merge are gated by the [trust ladder](/docs/trust-and-plans) (Max+),
  and merge additionally requires the repo's auto‑merge to be on.

## Related

- [The Verification Gate](/docs/verification-gate) · [Issue solving](/docs/issue-solving)
- [Trust ladder & plans](/docs/trust-and-plans) · [Security & data](/docs/security)