pr-review-go

README

pr-review-go

Multi-language AI PR Reviewer and Autonomous Assistant written in Go. Designed to inspect, test, and edit pull requests across any programming language (Go, Python, Node.js/TypeScript, Rust, Java/Maven/Gradle, Make, and more). Supports direct execution (SANDBOX_MODE=direct) for pre-isolated environments (Proxmox LXC, Docker, Kubernetes, CI runners) as well as rootless Podman container isolation on Linux.

Inspired by GitHub Copilot's agentic architecture and PR-Agent:

1. Multi-Language Verification: Detects project ecosystem (go.mod, package.json, pyproject.toml/requirements.txt, Cargo.toml, pom.xml, build.gradle, Makefile) and runs appropriate build and test verification suites.
2. Flexible Sandbox Modes: Choose between disposable rootless Podman container isolation (SANDBOX_MODE=podman) or containerless direct execution (SANDBOX_MODE=direct) in pre-isolated environments like Proxmox LXC.
3. Review Discussion & Thread Awareness: Gathers existing PR comments and inline review discussions. Tracks whether previous review feedback was addressed in new commits and prevents repeating resolved debates.
4. Discussion Summarizer (/summarize): Instantly compiles all PR comments, debates, and reviewer feedback into an executive summary table (zero sandbox overhead).
5. Interactive PR Assistant & Gated Editing: Responds to questions about PR code and securely applies requested modifications with automated verification before non-force commits.
6. SHA-256 Yorum Deduplication (pkg/dedup): Prevents duplicate spam findings across multiple /review runs on the same PR using deterministic SHA-256 fingerprinting.
7. Documentation Report (/add_docs, pkg/docgen): Scans PR code for undocumented functions/types and reports missing comments without modifying files.
8. Effort Levels (lite vs balanced): Choose between fast diff-only inspection (-effort lite) and workspace-assisted review (-effort balanced).
9. Auto-Labeler (/labels): Context-aware categorization using PR title, description, and diff.
10. Atomic Changelog Updates (/update-changelog): Compares immutable commit SHAs and commits via GitHub GraphQL CAS (createCommitOnBranch with expectedHeadOid). Aborts cleanly if branch moves.
11. Daemonless & Lightweight: Consumes only ~10-15 MB RAM as a daemon.

Architecture

cmd/
  pr-review-go/        # Dual-mode CLI & Server daemon
  pr-review-server/    # Dedicated Webhook server binary
  pr-review-sandbox-helper/ # Trusted helper binary inside container
pkg/
  config/              # Environment & LLM configuration
  github/              # GitHub API client (PRs, diffs, comments, discussions, GraphQL CAS)
  sandbox/             # Rootless Podman container runner (Linux) & API snapshot provider (macOS/Win)
  llm/                 # OpenAI-compatible / LiteLLM API client
  reviewer/            # Review orchestrator, prompt synthesis, and report formatting
  summarizer/          # Fast PR discussion & consensus summarizer
  assistant/           # Read-only interactive PR assistant (read_file, list_files)
  labeler/             # Auto-labeler based on PR contents
  changelog/           # Atomic changelog generation and expected-head CAS publication
  server/              # GitHub Webhook server with HMAC validation, durable bbolt queue & fixed workers
deploy/
  sandbox/             # Trusted Containerfile and helper build recipe
  pr-review.service   # Systemd unit template for Proxmox CT / Linux server

Quick Start

Install a release

Version tags such as v1.0.0 trigger tests, then publish a GitHub Release with Linux, macOS, and Windows archives for amd64 and arm64. Each archive contains pr-review-go and pr-review-server; checksums.txt contains SHA-256 checksums. Both binaries accept -version without requiring credentials.

The same tag publishes a multi-platform server image:

docker run --rm --env-file .env -p 3000:3000 ghcr.io/thozoz/pr-review-go:1.0.0

Images use explicit version tags; stable releases also update latest. Pre-releases do not replace latest. The Docker image includes Git for workspace cloning. Packaging does not change the documented host-clone and filesystem isolation limits of PR review.

After npm publishing is enabled, install both commands with:

npm install -g @thozoz/pr-review-go
pr-review-go -version
pr-review-server -version

The npm wrapper selects one of six platform packages through optional dependencies. Do not install with --omit=optional. npm publication is initially disabled and requires one-time npm Trusted Publisher configuration.

1. Build

go build -o bin/pr-review-go ./cmd/pr-review-go
go build -o bin/pr-review-server ./cmd/pr-review-server

2. Manual CLI Mode

export GITHUB_TOKEN="ghp_your_github_token_here"
export LLM_BASE_URL="https://api.openai.com/v1"
export LLM_API_KEY="your_api_key_here"
export LLM_MODEL="gpt-4o"

# Choose actions that run automatically when a PR opens.
# Omit AUTO_ACTIONS for the default: review,labels.
export AUTO_ACTIONS="review,labels,describe"

# Review a pull request directly
./bin/pr-review-go -pr https://github.com/owner/repo/pull/42

# Summarize existing discussions on a PR (no sandbox needed, fast)
./bin/pr-review-go -pr https://github.com/owner/repo/pull/42 -summary

# Ask read-only assistant about PR code (no commands are run)
./bin/pr-review-go -pr https://github.com/owner/repo/pull/42 -ask "Explain the changes in server.go"

# Only generate and apply labels
./bin/pr-review-go -pr https://github.com/owner/repo/pull/42 -labels

# Append an AI-generated purpose and file walkthrough to the PR body
./bin/pr-review-go -pr https://github.com/owner/repo/pull/42 -describe

# Add and commit one Keep a Changelog entry (skips author edits)
./bin/pr-review-go -pr https://github.com/owner/repo/pull/42 -update-changelog

3. 7/24 Webhook Daemon Mode (GitHub App / Webhook)

export WEBHOOK_SECRET="your-hmac-secret"
export PORT=3000

# Optional durable queue and capacity controls (defaults shown; WEBHOOK_STATE_DIR defaults to platform os.UserConfigDir()/pr-review-go/state):
export WEBHOOK_STATE_DIR="$HOME/.config/pr-review-go/state"
export WEBHOOK_WORKERS=2
export WEBHOOK_BACKLOG=100
export LLM_CONCURRENCY=2
export LLM_MIN_INTERVAL=1s
export SANDBOX_CONCURRENCY=1

./bin/pr-review-server

When running in server mode:

• Durable bbolt Ledger & Bounded Retention: Webhooks commit delivery receipts and job bundles atomically to jobs.db before returning HTTP 200. Bounded maintenance reclaims expired terminal records without evicting active work. Saturated queues return HTTP 503 (Retry-After: 30).
• Per-PR FIFO Serialization: Work is serialized per pull request; distinct PRs process in parallel across fixed workers.
• Automatic Review Coalescing: Subsequent commits during an active review coalesce into a single follow-up review of the latest commit; outdated reports are discarded before publication.
• Status Comment Recycling & Outbox: A dedicated background StatusOutbox publishes durable queued status comments immediately; transitions recycle the same status comment per PR.
• Rerun Protection: Repeated comment deliveries are deduplicated within the retention window; fresh /review comments on already-reviewed commits explicitly rerun and display "This commit was already reviewed. Reviewing again.".
• Offline Disaster Recovery: Blocked or crashed jobs can be inspected and resolved using WEBHOOK_STATE_DIR=/path ./bin/pr-review-server --queue-inspect and --queue-resolve (confirmed, rerun, cancel). Full configuration tables and recovery runbooks ship with the local operator docs.

Incoming webhook triggers:

• pull_request: opened -> auto-labels + code review
• pull_request: synchronize -> coalesced incremental review
• Comment /review -> triggers code review; project build/tests remain disabled
• Comment /approve -> publishes an APPROVE review from the bot identity, bound to the exact head SHA at execution time. Command-triggered only; automatic reviews stay COMMENT. One decision per head commit: a duplicate command for the same head is rejected with a warning comment, and a new commit requires a fresh command (the old record stays on the old commit in the GitHub UI). Whether the approval satisfies required reviews depends on repo branch protection; stale-approval dismissal on new commits ("Dismiss stale pull request approvals when new commits are pushed") is a repo setting the bot cannot control.
• Comment /request_changes -> publishes a REQUEST_CHANGES review under the same exact-head, one-decision-per-head, and bot-identity rules as /approve.
• Comment /improve -> posts an unavailable notice; no suggestions are generated
• Comment /describe -> appends a purpose and file walkthrough to PR body. Mermaid architecture diagrams are opt-in (default OFF): set ENABLE_MERMAID=1 or run an explicit /describe command to include a diagram; author text is never modified and re-runs replace only the diagram block.
• Comment /add_docs or /docs -> posts documentation suggestions as a PR comment. Permanently report-only: never modifies code, commits, or pushes, including after any future push work.
• Comment /update_changelog -> commits one changelog entry when author has not edited it
• Comment /summarize or /summary -> triggers discussion summary
• Comment /labels or /generate_labels -> triggers label generation
• Comment @bot <task>, @pr-review <task>, or /ask <task> -> launches interactive sandbox assistant

License

This project is licensed under the MIT License - see the LICENSE file for details.