AI GitHub PR Review Agent

An automated GitHub PR review agent powered by Google Gemini. It listens for GitHub webhook events, analyzes code diffs, and posts structured, actionable review comments directly on the PR.

---

✨ Features

• 🔐 Secure webhook handling — HMAC SHA-256 signature validation
• 🤖 Google Gemini-powered analysis — Gemini 1.5 Flash/Pro reviews your diff
• 🐛 Structured output — Bugs, suggestions, praise, and security concerns
• ⚡ Async queue — Non-blocking job processing via Redis + RQ
• 🗄️ Persistent logging — All reviews stored in PostgreSQL
• 🔁 Re-trigger command — Post /review in any PR comment to re-run
• 🐳 Docker Compose — One-command local setup

---

🏗️ Architecture

GitHub PR Event
     │
     ▼
POST /webhook (FastAPI)
  ├─ Verify HMAC SHA-256 signature
  ├─ Validate event type (opened/synchronize/reopened)
  └─ Enqueue job → Redis
               │
               ▼
         RQ Worker
  ├─ Fetch PR diff + metadata (GitHub REST API)
  ├─ Post "Review in progress..." comment
  ├─ Build prompt (context_builder)
  ├─ Call Google Gemini API
  ├─ Parse structured JSON response
  ├─ Update comment with full review (GitHub)
  └─ Log to PostgreSQL

Review Message

---

🚀 Quick Start

Prerequisites

• Docker Desktop
• A GitHub account with a repository you can test on
• A Google AI Studio API key (Gemini)
• A GitHub Personal Access Token (PAT) with repo scope

1. Clone and configure

git clone <your-repo-url>
cd "AI GitHub PR Review Agent"

# Copy the env template
cp .env.example .env

Edit .env and fill in your values:

GITHUB_TOKEN=ghp_your_token_here
GITHUB_WEBHOOK_SECRET=your_webhook_secret_here
GEMINI_API_KEY=your_gemini_key_here
GEMINI_MODEL=gemini-1.5-flash
DATABASE_URL=postgresql+asyncpg://postgres:postgres@postgres:5432/pr_review_agent
REDIS_URL=redis://redis:6379/0

2. Start the stack

docker-compose up --build

This starts:

Service	Port	Description
api	8000	FastAPI webhook receiver
worker	—	RQ background worker
redis	6379	Job queue
postgres	5432	Review log database

3. Expose your local server

Install ngrok and run:

ngrok http 8000

Copy the https://xxxx.ngrok.io URL.

4. Register the GitHub webhook

1. Go to your test repo on GitHub → Settings → Webhooks → Add webhook
2. Set Payload URL to: https://xxxx.ngrok.io/webhook
3. Set Content type to: application/json
4. Set Secret to the same value as GITHUB_WEBHOOK_SECRET in your .env
5. Select Individual events → check Pull requests and Issue comments
6. Click Add webhook

5. Open a pull request

Open a PR on your test repo and watch the agent post a review comment!

---

🔁 Re-triggering a Review

Post the following comment on any PR to re-run the review:

/review

---

🧪 Running Tests

# Install dependencies locally
pip install -r requirements.txt

# Run all tests
pytest

# Run with verbose output
pytest -v

# Run a specific test file
pytest tests/test_review_engine.py -v

---

📁 Project Structure

.
├── app/
│   ├── main.py                  # FastAPI entry point
│   ├── config.py                # Settings (pydantic-settings)
│   ├── models/
│   │   └── db_models.py         # SQLAlchemy ORM models
│   ├── db/
│   │   └── database.py          # Async DB session management
│   ├── routers/
│   │   └── webhook.py           # POST /webhook handler
│   ├── services/
│   │   ├── github_service.py    # GitHub API integration
│   │   ├── gemini_service.py    # Google Gemini LLM
│   │   ├── context_builder.py   # Prompt construction + Markdown formatter
│   │   └── review_engine.py     # Review pipeline orchestrator
│   └── workers/
│       └── pr_worker.py         # RQ background job
├── migrations/
│   └── init.sql                 # PostgreSQL schema
├── tests/
│   ├── test_webhook.py
│   ├── test_gemini_service.py
│   └── test_review_engine.py
├── .env.example
├── docker-compose.yml
├── Dockerfile
├── requirements.txt
└── README.md

---

⚙️ Configuration Reference

Variable	Required	Default	Description
GITHUB_TOKEN	✅	—	GitHub PAT with repo scope
GITHUB_WEBHOOK_SECRET	✅	—	Webhook secret (must match GitHub settings)
GEMINI_API_KEY	✅	—	Google AI Studio API key
GEMINI_MODEL	❌	gemini-1.5-flash	Model to use (gemini-1.5-pro for higher quality)
DATABASE_URL	❌	Local PostgreSQL	postgresql+asyncpg://...
REDIS_URL	❌	redis://localhost:6379/0	Redis connection string
LOG_LEVEL	❌	INFO	DEBUG, INFO, WARNING, ERROR
MAX_DIFF_BYTES	❌	102400 (100KB)	Max diff bytes sent to LLM
MAX_DIFF_LINES	❌	2000	Max diff lines sent to LLM

---

🔍 API Endpoints

Method	Path	Description
GET	/health	Health check
GET	/docs	Swagger UI
GET	/redoc	ReDoc UI
POST	/webhook	GitHub webhook receiver

---

🛡️ Security Notes

• The webhook secret is required — all requests without a valid HMAC signature are rejected with 401
• Your GITHUB_TOKEN and GEMINI_API_KEY are never logged or exposed
• Use a GitHub App instead of PAT for production deployments

---

📈 Roadmap

• GitHub App authentication (production-grade)
• Inline file-level review comments
• Multi-agent analysis (security agent, performance agent)
• Configurable review rules per repository
• Dashboard UI for reviewing history
• GitLab / Bitbucket support