github-pr-watcher

github-pr-watcher

Polls the GitHub Search API for open pull requests and publishes a CreateTaskCommand to Kafka for each new or force-pushed PR so the github-pr-review-agent picks it up automatically.

Links

Dev: https://dev.quant.benjamin-borbe.de/admin/maintainer-watcher-github-pr/setloglevel/3 https://dev.quant.benjamin-borbe.de/admin/maintainer-watcher-github-pr/check https://dev.quant.benjamin-borbe.de/admin/maintainer-watcher-github-pr/trigger?url=https://github.com/owner/repo/pull/123

Prod: https://prod.quant.benjamin-borbe.de/admin/maintainer-watcher-github-pr/setloglevel/3 https://prod.quant.benjamin-borbe.de/admin/maintainer-watcher-github-pr/check https://prod.quant.benjamin-borbe.de/admin/maintainer-watcher-github-pr/trigger?url=https://github.com/owner/repo/pull/123

How It Works

The watcher runs a user:<scope> GitHub Search query on a configurable interval. On each poll it compares the PR's current head SHA against the value stored in the cursor; if the SHA has changed (force-push) the PR is re-submitted as a new task. The cursor is persisted to /data/cursor.json between polls so a restart does not re-trigger every known PR.

Two independent decision chains run per PR — see docs/watcher-decision-chains.md:

• TaskCreationFilter — should we create a task at all? (drafts, bots, WIP titles, age, allowlist)
• TrustGate — given a task is created, auto-process or route to human_review? (trusted authors)

Environment Variables

REPO_ALLOWLIST syntax

Entries are comma-separated. A leading ! marks an exclusion. A target is allowed iff (includes is empty OR any include matches) AND (no exclude matches); excludes always override includes.

An allowlist consisting of only exclude entries is treated as allow-all-except: every target passes the include gate, and only the exclude gate filters. Example: REPO_ALLOWLIST=!github.com/bborbe/go-skeleton rejects go-skeleton and allows every other repo (including all other bborbe repos). To allow every bborbe repo except go-skeleton, write github.com/bborbe/*,!github.com/bborbe/go-skeleton.

.reviewignore — per-repo size-gate exclusion

MAX_ADDITIONS / MAX_CHANGED_FILES count the whole diff, so a PR that is mostly non-reviewable content parks even when the real code change is small. A repo opts out of that by committing a .reviewignore at its root:

# generated / vendored — nobody reviews these
vendor/
**/mocks/**
*.snap

# dark-factory pipeline state (NOT scenarios — those are shipped contracts)
prompts/
specs/

Syntax is gitignore: # comments, blank lines, ** depth wildcards, ! negation. Matched files are subtracted from both the added-line and changed-file counts before the park decision, so only reviewable content can trip the thresholds. The same exclusion is reported on the task body:

499 additions across 3 files excluded by `.reviewignore` (not counted toward the size gate, not sent to the reviewer).

Two properties are deliberate:

• The audit line appears on every review task, not only parked ones. Reporting it only on parks would hide the exclusion on exactly the PRs it rescued from parking.
• .reviewignore can never exclude itself. A pattern matching .reviewignore — directly, via *, or via negation ordering — has no effect: the file's own added lines always count toward the gate and never appear in the excluded total. A repo cannot use the file to conceal edits to the file.

An absent or empty .reviewignore excludes nothing, and any error reading it is treated the same way — a failure can only ever park more, never let an oversized PR through.

Negation and excluded parents

Matching follows git, including the gitignore rule that a file cannot be re-included once a parent directory is excluded:

specs/
!specs/README.md    # has NO effect — specs/ already excluded the parent

specs/README.md stays excluded. To exclude a directory's contents while keeping one file, exclude by pattern rather than by directory:

specs/*
!specs/README.md    # works — no parent directory was excluded

This is worth stating because the Go gitignore library backing the size gate does not implement that rule on its own; the matcher re-checks ancestor directories to restore it. The size gate and the reviewer prompt (which drives git's own ignore engine) must agree about the same file — otherwise a path the gate counts as reviewable would be withheld from the reviewer.

Metrics

All metrics use the github_pr_watcher_ prefix and are exposed on /metrics.

The scan runs once per poll cycle, after the cursor is saved and before the cycle is counted successful, so a slow or failing scan never changes the poll result. A failed or interrupted scan leaves the previous gauge values in place; only a complete scan replaces them (an empty result clears the gauge). With REVIEWER_BOT_LOGINS empty the feature is off: no extra GitHub calls, no github_pr_watcher_unreviewed_prs series, and the timestamp gauge stays 0.

A PR whose head SHA has been confirmed reviewed is remembered until it changes, so a settled PR costs no GetPRDetails/ListReviews calls on later scans. Any push, draft toggle, comment or label moves the PR's UpdatedAt and forces a fresh check.

Unreviewed retry

When a scan finds a PR still unreviewed, it re-publishes that PR's original review task — the same DeriveTaskID and the same create command the poll would send — up to UNREVIEWED_RETRY_MAX times per (PR, head SHA), one UNREVIEWED_THRESHOLD apart. A new commit is a new head SHA and starts a fresh budget; a pod restart can grant up to UNREVIEWED_RETRY_MAX more. The retry only ever re-sends the create command: it never forces a re-review, never mutates GitHub, and only fires after a complete, successful scan. Each retry logs one unreviewed retry … line and increments github_pr_watcher_unreviewed_retries_total.

Known limits:

• A retry cannot revive a task that already exists but never dispatched — only a new commit does. An exhausted PR needs a human.
• The agent controller dedups on the task title path, which embeds the slugified PR title, so editing a PR's title between the original publish and a retry can produce a second review task for the same commit.
• Each retry also increments github_pr_watcher_prs_total{command="create"} and may cost 1–2 extra GitHub calls (PublishCreate's .reviewignore lookup).
• On a cold start the poll can publish a PR and the scan can retry it in the same cycle — harmless (the controller dedups), but it counts as a retry.
• If PublishCreate keeps returning false (e.g. Kafka down), attempts never reach the budget, so retries_exhausted never flips — watch github_pr_watcher_prs_total{command="error"} for that case.

Known limitation: UpdatedAt moves on comments and label changes too — including the watcher's own trivial-PR label — which restarts the wait and can delay a report. Cost: about two core API calls per qualifying open PR (PR details + reviews), more for raw-oversized PRs that need the .reviewignore lookup, all on the shared App token.

HTTP Endpoints

Single-PR Trigger Known Limit

If a vault task already exists for the same (PR, SHA), the controller's create-if-not-exists is idempotent and no fresh agent Job spawns. To force a re-run in that case, reset the vault task's frontmatter (phase, status, trigger_count) manually OR push a new commit so the SHA changes.

Development

make test          # run unit tests
make generate      # regenerate counterfeiter mocks
make precommit     # format + lint + test + security checks

Cursor Mechanism

The cursor at /data/cursor.json records the timestamp of the most-recently-seen PR update plus a map of task_id → head_sha. On cold start (missing file) the cursor is initialised to the process start time minus BACKFILL_DURATION, so only PRs updated within that window are submitted. Force-push detection compares the stored head SHA for a known PR against the value returned by the current poll; a mismatch publishes a new CreateTaskCommand with the new SHA.

A corrupt cursor refuses startup — see pkg/cursor.go.

Relationship to pr-reviewer

This service feeds tasks into the github-pr-review-agent Pattern B Job via Kafka: for every new or force-pushed PR it publishes a CreateTaskCommand that the agent task controller picks up and spawns into a per-task K8s Job. The agent runs /coding:pr-review and posts the verdict back to the PR.

See docs/architecture.md for the full pipeline.

License

BSD 2-Clause License. See LICENSE.

Auto-merge arming window

Arming is not the same as merging, and it cannot be done at any time.

GitHub exposes auto-merge only through the GraphQL enablePullRequestAutoMerge mutation. There is no REST endpoint — PUT /repos/{owner}/{repo}/pulls/{number}/auto-merge returns 404 Not Found, which is why go-github ships no typed wrapper for it.

The mutation rejects a pull request that is already mergeable:

UNPROCESSABLE: Pull request Pull request is in clean status

Auto-merge is a promise to merge once the remaining requirements are met, so there must be a remaining requirement. A pull request that has already gone green and collected its approvals cannot be armed — at that point it can only be merged outright.

This matters because the watcher's search is cursor-based: a pull request is processed on the poll following its last update, so arming gets roughly one attempt per update. In the normal agent flow that attempt lands within one poll interval of PR creation, while CI is still running and no review exists yet, so the pull request is blocked and arming succeeds. A pull request that becomes mergeable faster than the poll interval will not be armed, and the watcher logs the refusal at error level rather than failing silently.