An enterprise-grade GitHub App and SaaS platform that automates code reviews using Google Gemini 2.5 Flash AI. It acts as an automated Senior Software Engineer living directly in your repository — analyzing Pull Request diffs, identifying security vulnerabilities, and posting structured, contextual feedback back to your GitHub timeline in seconds.
- Vercel Edge WAF: Next.js Edge Middleware natively blocks bot/DDoS attacks (
k6,jmeter) and ReDoS buffer overlow attempts before they hit serverless functions. - Server-Side API Proxies: Frontend environment secrets are fully removed from the browser. Client requests pipe through safe Next.js proxy routes.
- Aggressive Parameter Sanitization: Backend handles NoSQL injection blocking via
express-mongo-sanitize, HTTP parameter pollution viahpp, and rejects large payload attacks. - Client-side Protection: Strict security headers enforce HSTS & Anti-clickjacking, while user inputs are filtered via
DOMPurify. - SEO & Branding Update: Rebranded title and metadata:
AI PR Reviewer | Automated GitHub Code Analysis.
- Overview
- Key Features
- Demo
- Project Structure
- Software Requirements Specification (SRS)
- User Guide — Getting Started
- Developer Guide — Architecture & Setup
- API Reference
- Security
- Troubleshooting & FAQ
- Roadmap
- Contributing
- License
- Acknowledgements
The AI-Powered GitHub Pull Request Reviewer removes the bottleneck of manual code reviews in modern software teams. Once installed as a GitHub App, it automatically listens for Pull Request events and delivers in-depth AI-generated feedback — covering logic bugs, security vulnerabilities, performance anti-patterns, and style conventions — directly as a comment on the PR timeline.
Who is this for?
- Development Teams who want faster, consistent code reviews without reviewer burnout.
- Solo Developers who want a senior-engineer second opinion on every change.
- Open Source Maintainers who need to scale code quality enforcement across many contributors.
| Feature | Description |
|---|---|
| 🔍 Automated Code Analysis | Triggered on every opened, reopened, and synchronize PR event. |
| 🧠 AI-Powered Reviews | Google Gemini 2.5 Flash analyzes diffs, PR titles, and descriptions for holistic context. |
| 📝 Structured Markdown Reports | Review is posted as a formatted PR comment covering security, logic, and style issues. |
| ⚙️ Custom Rule Engine | Define your own prompt instructions per repository (e.g., "Enforce strict TypeScript"). |
| 📊 Analytics Dashboard | Track total scans, vulnerabilities flagged, and bugs caught over time. |
| 🔒 HMAC Payload Validation | Every incoming webhook is cryptographically verified using X-Hub-Signature-256. |
| 🔑 Short-lived Auth Tokens | GitHub Installation Access Tokens are generated on-demand and never persisted. |
| 🚦 Rate Limiting | Express rate-limiter protects all API and webhook endpoints from abuse. |
Hosted SaaS: https://pr-agent-test.vercel.app
How it works in 3 steps:
- Install the GitHub App on your repository.
- Paste your Gemini API Key into the dashboard.
- Open any Pull Request — the AI review appears automatically within seconds.
Example AI Review Output (posted as a PR comment):
## 🤖 AI Code Review
### 🔴 Security Issues
- Line 42 (`auth.js`): Hardcoded JWT secret detected. Move to environment variable.
### 🟡 Logic Bugs
- Line 78 (`user.service.js`): `findOne` result not null-checked before property access.
### 🟢 Suggestions
- Consider memoizing the `calculateMetrics` function to avoid redundant computation.
### ✅ Summary
Overall quality: Good. 2 issues require attention before merging.
pr-agent-test/
├── pr-review-agent/ # Backend — Node.js / Express
│ ├── controllers/
│ │ ├── webhook.controller.js # Handles incoming GitHub webhook events
│ │ └── settings.controller.js# User settings and review retrieval
│ ├── models/
│ │ ├── Account.js # Mongoose model for user accounts & API keys
│ │ └── Review.js # Mongoose model for storing AI review history
│ ├── services/ # Business logic (AI inference, GitHub API calls)
│ ├── server.js # Express app entry point
│ ├── private-key.pem # GitHub App private key (NOT committed — add to .gitignore)
│ └── .env # Backend environment variables (see configuration)
│
├── pr-reviewer-frontend/ # Frontend — Next.js 16 (App Router)
│ ├── app/ # Next.js App Router pages and layouts
│ ├── public/ # Static assets
│ ├── next.config.ts
│ └── .env.local # Frontend environment variables (see configuration)
│
├── test.js # Integration / smoke tests
└── README.MD # This file
This system provides a unified code-quality workflow integrated directly into GitHub's ecosystem. It operates across two environments:
- Frontend Dashboard (SaaS Platform): A Next.js application where developers authenticate, link their repositories, manage AI behavior via custom prompts, and monitor repository security metrics.
- Backend Webhook Handler: A Node.js service that receives events from GitHub Webhooks, orchestrates AI analysis, and delivers feedback via the GitHub API.
| User Type | Description |
|---|---|
| Repository Admins / Maintainers | Configure SaaS settings, provide Gemini API keys, write custom review rules, and manage GitHub App permissions. |
| Contributors / Code Authors | Open pull requests and receive automated feedback directly in GitHub without any additional tooling. |
| Developers (Self-Hosted) | Clone the repo, configure environment variables, and run both services locally with their own credentials. |
1. Automated Context-Aware Code Analysis
- Trigger: GitHub
pull_requestevents (opened,reopened,synchronize). - Action: Parses PR titles, descriptions, and code diffs. Feeds the compiled context to Google Gemini to deduce intent and detect anomalies.
- Output: A markdown-formatted report posted as a PR comment, mapping vulnerabilities, logic bugs, and style issues.
2. Custom Agent Prompting (Rule Engine)
- Users can append or override specific AI instructions (e.g.,
"Ignore trailing spaces","Focus on React Server Components best practices"). Rules are stored securely in MongoDB and attached to every AI review query.
3. Analytics & Tracking Dashboard
- Tracks key metrics over time: total scans executed, vulnerabilities flagged, and logic bugs identified — visible on a unified dashboard.
4. Secure Settings Management
- User Gemini API keys and custom rules are stored per GitHub username in MongoDB and never logged or exposed in API responses.
| Category | Requirement |
|---|---|
| Security | Payload HMAC validation, Next.js Edge Middleware for DDoS mitigation, XSS & NoSQL Injection blocking, strict HTTP headers, and proxy-routed API secrets. |
| Authentication | OAuth 2.0 via GitHub (NextAuth). Short-lived GitHub App Installation Access Tokens generated per request. |
| Scalability | Event-driven architecture allows the webhook handler to be extracted as a serverless function. |
| Performance | AI review delivery target: under 30 seconds from PR event to posted comment. |
| Reliability | MongoDB Atlas for persistent storage; Express process managed by nodemon in development. |
No code required! If you are using the hosted SaaS version at pr-agent-test.vercel.app, follow Steps 1–3 only.
- Navigate to the GitHub Pull Request Reviewer GitHub App installation page (linked from the dashboard landing page).
- Click Install.
- Select All Repositories or Only select repositories depending on your preference.
- You will be automatically redirected to the web dashboard.
- On the dashboard, click Login with GitHub to authenticate securely via OAuth.
- Go to the Settings tab and enter your Google Gemini API Key.
- Get a free key at Google AI Studio.
- (Optional) Define Custom AI Rules to tailor the review style:
"Focus on catching memory leaks in React""Ignore CSS formatting issues""Ensure all async functions have proper error handling"
- Navigate to any connected GitHub repository.
- Create a new branch, make code changes, and open a Pull Request.
- Done! The AI reviewer will post a detailed review comment on your PR within seconds.
┌─────────────────────────────────────────────────────────┐
│ GitHub Platform │
│ User installs GitHub App → PR opened → Webhook fired │
└───────────────────────┬─────────────────────────────────┘
│ POST /webhook
▼
┌─────────────────────────────────────────────────────────┐
│ Backend (Express / Node.js) │
│ 1. Validate HMAC signature (X-Hub-Signature-256) │
│ 2. Look up user settings in MongoDB │
│ 3. Generate GitHub Installation Access Token (JWT) │
│ 4. Fetch PR diff via GitHub REST API │
│ 5. Build prompt (diff + custom rules) → Gemini API │
│ 6. Parse AI response → Post markdown comment via API │
└───────────────────────┬─────────────────────────────────┘
│
┌────────────┴────────────┐
▼ ▼
┌─────────────────┐ ┌─────────────────────────┐
│ MongoDB │ │ Google Gemini 2.5 Flash │
│ (User settings │ │ (AI inference engine) │
│ & reviews) │ └─────────────────────────┘
└─────────────────┘
┌─────────────────────────────────────────────────────────┐
│ Frontend Dashboard (Next.js 16) │
│ - GitHub OAuth login (NextAuth) │
│ - Gemini API key input & custom rule editor │
│ - Analytics dashboard (scans, bugs, vulnerabilities) │
└─────────────────────────────────────────────────────────┘
End-to-end flow:
- GitHub Installation: User installs the GitHub App and is redirected to the Next.js SaaS Dashboard.
- Dashboard Configuration: User authenticates, stores their Gemini API key, and writes custom prompt rules. The Next.js frontend persists this via the Express API into MongoDB.
- PR Trigger: A PR is opened. GitHub sends an event payload to the
/webhookendpoint. - Validation & Token Generation: The Express server verifies the payload HMAC, retrieves user settings from MongoDB, and generates a short-lived GitHub Installation JWT.
- AI Inference: The PR diff is fetched, combined with the user's custom rules, and sent to Gemini.
- Delivery: The AI-generated response is formatted as GitHub Markdown and posted as a PR comment.
| Layer | Technology |
|---|---|
| Frontend | Next.js 16 (App Router), TypeScript, Tailwind CSS v4, NextAuth.js, Vercel Edge Middleware |
| Backend | Node.js, Express.js v5 |
| Database | MongoDB (Mongoose ODM) |
| AI | @google/generative-ai — Gemini 2.5 Flash |
| Security | crypto (HMAC), helmet, express-rate-limit, dompurify, hpp, express-mongo-sanitize |
| Dev Tools | nodemon, dotenv |
Before setting up the project locally, ensure you have:
- Node.js v18+ — Download
- MongoDB — Local instance or a free MongoDB Atlas cluster
- GitHub Developer Account — Register a new GitHub App
- Google AI Studio Account — Get a Gemini API Key
- Ngrok (or LocalTunnel) — To expose your local server publicly for webhook delivery: Download Ngrok
Create this file and populate all values:
# Server
PORT=5000
# Database
MONGODB_URI=mongodb+srv://<user>:<password>@cluster.mongodb.net/pr-reviewer
# GitHub App Credentials
GITHUB_WEBHOOK_SECRET=a_random_secret_you_define_in_github_app_settings
GITHUB_APP_ID=123456
# Internal security — shared between frontend and backend
FRONTEND_SECRET=a_long_random_secure_string
⚠️ Important: Download your GitHub App's private key (.pemfile) from the GitHub App settings page and save it asprivate-key.pemin the/pr-review-agent/directory. This file must never be committed to version control.
# Backend API base URL
NEXT_PUBLIC_API_URL=http://localhost:5000
# NextAuth configuration
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=another_long_random_secure_string
# GitHub OAuth App credentials (from github.com/settings/developers)
GITHUB_ID=your_oauth_app_client_id
GITHUB_SECRET=your_oauth_app_client_secret💡 Tip: Use
openssl rand -base64 32to generate strong random secrets forNEXTAUTH_SECRETandFRONTEND_SECRET.
Step 1 — Start the Backend
cd pr-review-agent
npm install
npm run devThe backend starts on http://localhost:5000.
Step 2 — Expose Webhook Endpoint to the Internet
Open a new terminal window and run:
ngrok http 5000Copy the HTTPS forwarding URL (e.g., https://abc123.ngrok.io) and paste it into your GitHub App Settings → Webhook URL as:
https://abc123.ngrok.io/webhook
Step 3 — Start the Frontend Dashboard
Open another terminal window and run:
cd pr-reviewer-frontend
npm install
npm run devNavigate to http://localhost:3000 to access the dashboard.
Security is deeply integrated into every layer of this platform. For our comprehensive disclosure policy, see SECURITY.md.
Key Defense Layers:
- Code-First WAF (Edge): Client-facing URLs are shielded by Vercel Edge Middleware. It intercepts traffic instantly, identifies load-runner bots (like k6 and JMeter), truncates malicious buffer-overflow attempts, and drops packets at the CDN level.
- Frontend Hardening: Sensitive keys (for the API) never reach the browser. Next.js server-side proxies carry out authorized actions. XSS is prevented via
DOMPurifyinput scrubbing and regex-backed form validation. - Backend Throttling & Sanitization: Dual-layer
express-rate-limitpolicies ensure webhook listeners and backend APIs are resilient to flooding. Packages likeexpress-mongo-sanitizeblock NoSQL injections, and strict payload size checks drop gigabyte-sized DDoS packets. - Webhooks: Every webhook received is cryptographically validated using
X-Hub-Signature-256HMAC via the securely stored GitHub App Secret.
The backend exposes the following REST endpoints:
Receives and processes GitHub pull request events.
| Property | Value |
|---|---|
| Auth | X-Hub-Signature-256 HMAC (auto-validated) |
| Rate Limit | 10 requests / 10 minutes per IP |
| Payload | GitHub webhook event JSON |
Save or update user settings (Gemini API key and custom rules).
| Property | Value |
|---|---|
| Auth | x-frontend-secret header required |
| Rate Limit | 10 requests / 10 minutes per IP |
Request Body:
{
"username": "github-username",
"geminiApiKey": "AIza...",
"customRules": "Focus on security vulnerabilities and memory leaks."
}Retrieve settings for a specific GitHub user.
| Property | Value |
|---|---|
| Auth | x-frontend-secret header required |
| Rate Limit | 10 requests / 10 minutes per IP |
Response:
{
"username": "github-username",
"customRules": "Focus on security vulnerabilities and memory leaks."
}Note: The Gemini API key is never returned in API responses.
Retrieve all AI review records for a specific GitHub user (used by the analytics dashboard).
| Property | Value |
|---|---|
| Auth | x-frontend-secret header required |
| Rate Limit | 10 requests / 10 minutes per IP |
Response:
[
{
"repo": "my-org/my-repo",
"prNumber": 42,
"prTitle": "Add user authentication",
"reviewPostedAt": "2025-01-15T10:30:00Z",
"vulnerabilitiesFound": 1,
"bugsFound": 2
}
]This project implements multiple security layers:
- Webhook HMAC Verification: All incoming GitHub webhook payloads are verified using
X-Hub-Signature-256with thecryptomodule. Requests with invalid or missing signatures are rejected with401 Unauthorized. - Short-lived GitHub Tokens: GitHub Installation Access Tokens are generated per-request using a signed JWT and are never stored in the database.
- HTTP Security Headers:
helmetis applied to set secure HTTP headers (CSP, HSTS, etc.) on all responses. - Rate Limiting:
express-rate-limitrestricts all/webhookand/api/*endpoints to 10 requests per 10 minutes per IP to prevent abuse. - Strict CORS: The backend only accepts requests from the configured frontend origin.
- Secret Isolation: Gemini API keys are stored in MongoDB per user and are never returned in any API response.
To report a security vulnerability, please open a private security advisory in the GitHub repository rather than a public issue.
- Check the backend logs — Ensure the Express server started without errors.
- Verify the webhook URL — Confirm the Ngrok/public URL in your GitHub App settings matches your running backend.
- Check webhook deliveries — Go to GitHub App Settings → Advanced → Recent Deliveries to inspect payload status and response codes.
- Validate your Gemini API Key — Ensure the key is saved in the dashboard Settings tab and has not expired.
This means the GITHUB_WEBHOOK_SECRET in your .env does not match the secret set in your GitHub App settings. Ensure both are identical.
The backend performs a startup check for all required environment variables. Confirm your MONGODB_URI is correct and your IP is whitelisted in MongoDB Atlas (or use 0.0.0.0/0 for development).
Verify NEXT_PUBLIC_API_URL in /pr-reviewer-frontend/.env.local points to the correct backend URL (default: http://localhost:5000).
- Visit Google AI Studio.
- Sign in with a Google account.
- Click Get API Key → Create API Key.
- Copy the key and paste it into the dashboard Settings page.
Yes. When you install the GitHub App, you can grant it access to private repositories. The app uses GitHub Installation Access Tokens scoped to only the repositories you select.
- Inline Review Comments — Post suggestions directly on specific diff lines instead of a single PR comment.
- Multi-model Support — Allow users to choose between Gemini, OpenAI GPT-4o, and Anthropic Claude.
- Review History Filtering — Filter analytics dashboard by repository, date range, or severity.
- Slack / Teams Notifications — Notify teams when a review identifies high-severity issues.
- GitHub Actions Integration — Offer the reviewer as a reusable GitHub Actions workflow step.
- Webhook Queue — Add a message queue (Redis/BullMQ) for reliable at-least-once webhook delivery.
- Self-hosted Docker Image — Provide a
docker-compose.ymlfor one-command self-hosted deployment.
Contributions are warmly welcome! Please follow these steps:
- Fork the repository.
- Create a feature branch:
git checkout -b feature/your-feature-name
- Commit your changes with a descriptive message:
git commit -m "feat: add inline review comments support" - Push to your fork:
git push origin feature/your-feature-name
- Open a Pull Request against the
mainbranch with a clear description of your change.
Guidelines:
- Follow the existing code style.
- Keep pull requests focused on a single change.
- Write or update tests where applicable.
- Ensure all environment variable changes are reflected in this README.
This project is licensed under the ISC License. See the LICENSE file for details.
- Google Gemini for the powerful and accessible generative AI API.
- GitHub for the GitHub Apps platform and REST API.
- Next.js and Vercel for the frontend framework and hosting.
- MongoDB Atlas for the managed database service.
- NextAuth.js for the seamless OAuth integration.
Built as a Full-Stack AI project automating modern DevSecOps lifecycle operations.