Skip to content
BranchesTags

Repository files navigation


🛡️ PRGuard

Your code's last line of defense

AI-powered Pull Request reviewer that scores, comments, auto-fixes, and blocks bad code from reaching production.


Live Demo Python FastAPI Groq Railway License


📖 What is PRGuard?

PRGuard is a GitHub bot that automatically reviews every Pull Request using LLaMA 3.3 running on Groq. It scores your code 0–10, posts inline comments on problem lines, creates auto-fix branches with AI-applied corrections, and sets a green ✅ or red ❌ commit status — all within seconds of opening a PR.

No configuration required. Just add the webhook and it works.

⚡ How PRGuard Works

Here is the complete step-by-step flow from PR to review:

Developer pushes code → GitHub sends webhook → PRGuard reviews → Results posted

Step 1 — Developer opens a Pull Request

A developer pushes code to a branch and opens a PR on GitHub.

Step 2 — GitHub sends a webhook event

GitHub instantly sends a POST request to PRGuard's webhook endpoint with the PR payload.

Step 3 — Signature verified

PRGuard verifies the HMAC-SHA256 webhook signature to confirm the request is genuine.

Step 4 — Diff fetched

PRGuard calls the GitHub API to fetch the full code diff of the PR.

Step 5 — Custom rules loaded

PRGuard checks if a prguard.yml file exists in the repo root and loads any custom rules and threshold.

Step 6 — AI reviews the code

The diff + custom rules are sent to LLaMA 3.3 via Groq. The model scores the code 0–10 and identifies issues across 8 categories.

Step 7 — Inline comments posted

PRGuard posts a comment directly on each problem line in the diff with severity, category, description, and fix.

Step 8 — Summary comment posted

A formatted summary comment is posted on the PR with the score bar, verdict, and all issues in collapsible sections.

Step 9 — Auto-fix branch created (if PR failed)

PRGuard creates a new branch prguard/fix-pr-{number}-{sha}, applies AI corrections to each affected file, and pushes the fixes.

Step 10 — Review saved to database

The review result is saved to PostgreSQL for dashboard analytics and chat history.

Step 11 — Commit status set

GitHub commit status is set to ✅ success (score ≥ threshold) or ❌ failure (score < threshold).

Step 12 — Developer can chat with the bot

Developer comments /prguard <question> on the PR and the bot replies with a context-aware answer.

┌─────────────────────────────────────────────────────────────┐
│                     PRGuard Pipeline                         │
├──────────┬──────────┬──────────┬──────────┬────────────────┤
│  Step 1  │  Step 2  │  Step 3  │  Step 4  │    Step 5      │
│  PR Open │ Webhook  │ Verify   │  Fetch   │  Load Rules    │
│          │  Event   │   Sig    │   Diff   │  prguard.yml   │
├──────────┼──────────┼──────────┼──────────┼────────────────┤
│  Step 6  │  Step 7  │  Step 8  │  Step 9  │   Step 10-12  │
│ AI Review│ Inline   │ Summary  │ Auto-Fix │  Save + Status │
│  Groq    │Comments  │ Comment  │  Branch  │  + Chat        │
└──────────┴──────────┴──────────┴──────────┴────────────────┘

✨ Features

Feature Description
🤖 AI Code Review Scores every PR 0–10 across 8 quality categories
💬 Inline Comments Posts issues directly on the affected line in the diff
🔥 Auto-Fix Branch Creates a prguard/fix-pr-* branch with AI-applied corrections
📊 Team Dashboard Live dashboard with score trends, pass rates, and issue breakdown
⚙️ Custom Rules Define team standards in prguard.yml — bot enforces them automatically
💬 PR Chat Comment /prguard <question> to ask the bot anything about the review
🔄 Smart Retry Handles API rate limits with exponential backoff (4 attempts)
✅ Commit Status Sets GitHub green ✅ or red ❌ check on every PR

🔍 Review Categories

PRGuard checks 8 categories on every PR — plus any custom rules you define:

Category What It Checks
🏷️ Naming Single letters, abbreviations, misleading variable names
🧩 Complexity Functions >30 lines, deeply nested conditionals
♻️ Duplication Repeated logic blocks without abstraction
⚠️ Error Handling Missing try/except on I/O, network, and DB calls
🔢 Magic Values Hardcoded strings/numbers that should be constants or config
🔐 Security Secrets in code, SQL injection, missing input validation
🛡️ Type Safety Missing type hints in Python, implicit any in TypeScript
💀 Dead Code Commented-out blocks, unused imports and variables
📋 Custom Your team's own rules from prguard.yml

📊 Scoring System

Score Grade Meaning
9–10 ⭐ Excellent Near-perfect. Ready to merge.
7–8 ✅ Good Acceptable. Minor issues only.
5–6 ⚠️ Borderline Real problems. Fix before merging.
3–4 ❌ Poor Multiple critical issues. Do not merge.
0–2 🚨 Unacceptable Rewrite required.

Multiple HIGH severity issues cannot score above 6.

⚙️ Custom Rules (prguard.yml)

Drop a prguard.yml file in your repo root to enforce team-specific standards:

rules:
  - "All functions must have docstrings"
  - "No print() statements allowed in production code"
  - "All HTTP calls must have timeout set explicitly"
  - "Database calls must use transactions"
threshold: 8

PRGuard picks this up automatically on every PR — no restarts needed.

💬 PR Chat

Comment /prguard <question> directly on any PR:

/prguard what is the most critical issue to fix first?
/prguard how do I fix the complexity issue in main.py?
/prguard why did this PR fail?

The bot replies with a detailed, context-aware answer based on the actual review results.

🏗️ Architecture

GitHub PR Event
      │
      ▼
┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│   Webhook   │────▶│  FastAPI App │────▶│  Groq API   │
│  (GitHub)   │     │  (Railway)   │     │ LLaMA 3.3   │
└─────────────┘     └──────┬───────┘     └─────────────┘
                           │
              ┌────────────┼────────────┐
              ▼            ▼            ▼
        ┌──────────┐ ┌──────────┐ ┌──────────┐
        │  Inline  │ │ Auto-Fix │ │Dashboard │
        │ Comments │ │  Branch  │ │(Postgres)│
        └──────────┘ └──────────┘ └──────────┘

Project Structure

PRGuard/
├── app/
│   ├── main.py           # FastAPI app & webhook handler
│   ├── ai_reviewer.py    # Groq review engine + retry logic
│   ├── auto_fixer.py     # Auto-fix branch creator
│   ├── github_client.py  # GitHub API wrapper
│   ├── formatter.py      # PR comment formatting
│   ├── database.py       # PostgreSQL storage
│   ├── dashboard.html    # Mission Control UI
│   ├── home.html         # Landing page
│   ├── rules.py          # prguard.yml parser
│   ├── chat.py           # /prguard chat handler
│   ├── models.py         # Pydantic data models
│   └── config.py         # Settings & env vars
├── prguard.yml           # Custom rules example
├── Procfile              # Railway start command
└── requirements.txt

🚀 Getting Started

Prerequisites

  • Python 3.11+
  • GitHub account & personal access token
  • Groq API key (free tier available)
  • ngrok for local development

1. Clone & Install

git clone https://github.com/AtharvaVavhal/PRGuard.git
cd PRGuard
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

2. Configure Environment

Create a .env file in the project root:

GITHUB_TOKEN=your_github_personal_access_token
GITHUB_WEBHOOK_SECRET=your_webhook_secret
GROQ_API_KEY=your_groq_api_key
GROQ_MODEL=llama-3.3-70b-versatile
PASS_SCORE_THRESHOLD=7
LOG_LEVEL=INFO
DATABASE_URL=postgresql://...        # Railway provides this automatically

3. Run Locally

# Start ngrok tunnel
ngrok http 8000

# Start the server
uvicorn app.main:app --port 8000

4. Set Up GitHub Webhook

  1. Go to your repo → Settings → Webhooks → Add webhook
  2. Payload URL: https://your-ngrok-url/webhook/github
  3. Content type: application/json
  4. Secret: your webhook secret
  5. Events: select Pull requests and Issue comments

5. Add Custom Rules (Optional)

# prguard.yml — place in your repo root
rules:
  - "All functions must have docstrings"
  - "No hardcoded API keys"
threshold: 7

☁️ Deploy to Railway

# 1. Fork this repo on GitHub
# 2. Go to railway.app → New Project → Deploy from GitHub repo
# 3. Add PostgreSQL database to the project
# 4. Set all environment variables in the Variables tab
# 5. Railway auto-deploys on every push ✅

Update your GitHub webhook URL to https://your-app.up.railway.app/webhook/github.

🔧 Tech Stack

Layer Technology
API Framework FastAPI + Uvicorn
AI Model LLaMA 3.3 70B via Groq
GitHub Integration GitHub REST API v3
Database PostgreSQL
HTTP Client httpx
Config Parsing PyYAML
Deployment Railway
Language Python 3.11

🤝 Contributing

Contributions are welcome!

# 1. Fork the repo
# 2. Create your feature branch
git checkout -b feature/my-feature

# 3. Commit your changes
git commit -m 'add my feature'

# 4. Push and open a PR
git push origin feature/my-feature

PRGuard will automatically review your PR. Meta. 🤖

📄 License

MIT License — see LICENSE for details.

Built with ❤️  ·  Powered by Groq + LLaMA 3.3  ·  Deployed on Railway


⭐ Star this repo if PRGuard saved your codebase!


🌐 Live Demo  ·  🐛 Report Bug  ·  💡 Request Feature

About

🛡️ AI-powered GitHub bot that reviews PRs, scores code quality, posts inline comments, auto-fixes issues, and blocks bad code from merging — powered by LLaMA 3.3 on Groq.

prguard-production-eae8.up.railway.app/

Topics

aiautomationcode-qualitycode-reviewdeveloper-toolsdevtoolsfastapigithub-actionsgithub-botgroqllamallmopen-sourcepostgresqlpull-requestpythonrailwaywebhook

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages