pr-reviewer

Automated pull request review service for Forgejo. Receives webhook events, sends diffs to an LLM for review, and posts the review as a comment on the PR.

How it works

1. A Forgejo webhook fires on PR open/synchronize/reopen/review_requested
2. pr-reviewer determines the review tier:
   • Quick scan (always): focused on bugs, security issues, and breaking changes
   • Full review (when pr-reviewer-bot is assigned as reviewer): thorough analysis including full file contents for context
3. A "working on it" comment is posted immediately with a timing estimate
4. The diff (and file contents for full reviews) is sent to the configured LLM backend
5. The pending comment is updated in-place with the review

After a full review is completed, the bot leaves the PR alone unless re-triggered by a new review_requested event or a comment mentioning @pr-reviewer-bot.

Configuration

All configuration is via environment variables:

Variable	Description	Default
FORGEJO_URL	Forgejo base URL	http://forgejo.forgejo.svc.cluster.local
FORGEJO_TOKEN	API token for the bot user	(required)
WEBHOOK_SECRET	HMAC-SHA256 secret for webhook verification	(required)
LLM_BACKEND	anthropic or vllm	anthropic
ANTHROPIC_API_KEY	Anthropic API key	(required if backend=anthropic)
VLLM_BASE_URL	vLLM endpoint	http://vllm.vllm.svc.cluster.local:8000/v1
ALLOWED_REPOS	Comma-separated repo allowlist (empty = allow all)	(empty)
BOT_USERNAME	Bot's Forgejo username	pr-reviewer-bot
DEFAULT_SETTLE_SECONDS	Initial settle delay before committing to quick scan	5.0
MAX_SETTLE_SECONDS	Ceiling for adaptive settle time	60.0
MAX_SETTLE_GAP_SECONDS	Gaps beyond this aren't considered near-misses	300.0
QUICK_SCAN_MAX_TOKENS	Max LLM output tokens for quick scans	2048
FULL_REVIEW_MAX_TOKENS	Max LLM output tokens for full reviews	8192
DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD	PostgreSQL connection	(from CNPG secret)

Endpoints

Webhook service (main:app)

Path	Description
POST /webhook	Forgejo webhook receiver
GET /health	Health check

Dashboard (dashboard:app)

Path	Description
GET /	Monitoring dashboard (event log, token usage, settle time)
GET /health	Health check

Setup

Forgejo bot user

Create a user (e.g. pr-reviewer-bot) with an API token that has:

• read:repository
• write:repository
• write:issue

The bot must be added as a collaborator (write access) on each repo it reviews.

Per-repo webhook

In each repo's Settings > Webhooks, add:

• URL: http://pr-reviewer.pr-reviewer.svc.cluster.local:8080/webhook
• Content type: application/json
• Secret: must match WEBHOOK_SECRET
• Trigger: Pull Request events

Deployment

Deployed to Kubernetes via Flux from the infra repo (apps/pr-reviewer/). Two deployments share the same image:

• pr-reviewer — webhook service (ClusterIP on 8080)
• pr-reviewer-dashboard — read-only dashboard (MetalLB, serves at /)

Container images are built locally and pushed to Harbor at harbor.brooktrails.org/brooktrails/pr-reviewer.

Dashboard

An internal-only MetalLB service exposes the dashboard on the local network. Check kubectl -n pr-reviewer get svc pr-reviewer-dashboard for the assigned IP, then visit http://<ip>/.

Contributing

Changes to this repo go through branches and pull requests, not direct pushes to main. Use the following branch prefixes:

• feat/ — new features
• fix/ — bug fixes
• refactor/ — restructuring without behavior changes
• doc/ — documentation updates

The pr-reviewer bot reviews its own PRs.