Skip to content

QUICK_START.md

Latest commit

 

History

History
267 lines (196 loc) · 5.83 KB

QUICK_START.md

File metadata and controls

267 lines (196 loc) · 5.83 KB

PR-Sentinel Quick Start Guide

Get PR-Sentinel running in 5 minutes!

Prerequisites

  • Python 3.8+ or Docker
  • GitHub Personal Access Token (Create one here)
    • Required permissions: repo (Full control of private repositories)

Option 1: Local Python Setup (Fastest)

# 1. Clone the repository
git clone https://github.com/Anorak001/PR-Sentinel.git
cd PR-Sentinel

# 2. Install dependencies
pip install -r requirements.txt

# 3. Create configuration
cp .env.example .env

# 4. Edit .env and add your GitHub token
nano .env
# Set: GITHUB_TOKEN=your_token_here

# 5. Run the server
python main.py

# Server is now running at http://localhost:8000

Option 2: Docker Setup (Recommended for Production)

# 1. Clone the repository
git clone https://github.com/Anorak001/PR-Sentinel.git
cd PR-Sentinel

# 2. Create .env file
cat > .env << EOF
GITHUB_TOKEN=your_token_here
GITHUB_WEBHOOK_SECRET=your_secret_here
SPAM_SCORE_THRESHOLD=70
EOF

# 3. Start with Docker Compose
docker-compose up -d

# 4. Check logs
docker-compose logs -f

# Server is now running at http://localhost:8000

Testing the Installation

# Check health
curl http://localhost:8000/health
# Expected: {"status":"healthy"}

# Check service info
curl http://localhost:8000/
# Expected: {"service":"PR-Sentinel","status":"running",...}

# Check stats
curl http://localhost:8000/stats
# Expected: {"total_tracked":0,"spam_detected":0,"recent_prs":[]}

Setting Up GitHub Webhook

Step 1: Get Your Server URL

Local testing with ngrok:

# Install ngrok from https://ngrok.com/download
ngrok http 8000

# Copy the HTTPS URL (e.g., https://abc123.ngrok.io)

Production:

  • Use your server's public domain or IP
  • Example: https://pr-sentinel.yourdomain.com

Step 2: Configure GitHub Webhook

  1. Go to your repository on GitHub
  2. Click Settings → Webhooks → Add webhook
  3. Fill in:
    • Payload URL: https://your-domain.com/webhook
    • Content type: application/json
    • Secret: (Optional but recommended) Same as GITHUB_WEBHOOK_SECRET in .env
    • Which events?: Select "Let me select individual events"
      • ✅ Check Pull requests
      • ❌ Uncheck everything else
    • Active: ✅ Checked
  4. Click Add webhook

Step 3: Test the Webhook

  1. Create a test PR in your repository with minimal changes
  2. Check PR-Sentinel logs: 
    # Docker
docker-compose logs -f

# Local
# Check terminal where python main.py is running
  3. Check stats: 
    curl http://localhost:8000/stats

Quick Configuration

Adjust Spam Threshold

Edit .env:

# More lenient (fewer auto-closes)
SPAM_SCORE_THRESHOLD=80

# More strict (more aggressive)
SPAM_SCORE_THRESHOLD=60

# Default (balanced)
SPAM_SCORE_THRESHOLD=70

Restart the service after changes:

# Docker
docker-compose restart

# Local
# Press Ctrl+C and run python main.py again

Test Without Closing PRs (Dry Run)

Add to config.py:

DRY_RUN = True  # Will log actions but not actually close PRs

Common Issues & Solutions

Issue: "GitHub token not provided"

Solution: Set GITHUB_TOKEN in .env file

Issue: Webhook returns 401 Unauthorized

Solution:

  • Check that GITHUB_WEBHOOK_SECRET matches in both .env and GitHub webhook settings
  • OR remove the secret from both places (less secure but works for testing)

Issue: Port 8000 already in use

Solution:

# Option 1: Use different port
PORT=8080 python main.py

# Option 2: Kill process using port 8000
lsof -ti:8000 | xargs kill -9

Issue: Module not found errors

Solution:

pip install -r requirements.txt

Issue: Can't connect from GitHub

Solution:

  • Make sure your server is publicly accessible
  • Check firewall rules
  • For local testing, use ngrok

Next Steps

  1. Monitor Performance

    • Check /stats regularly
    • Review logs for false positives
    • Adjust threshold if needed

  2. Customize Detection

    • See CUSTOMIZATION.md for advanced configuration
    • Add custom patterns for your repository's spam

  3. Deploy to Production

    • See DEPLOYMENT.md for cloud deployment options
    • Use Docker for easier deployment
    • Set up monitoring and alerts

  4. Review Documentation

    • README.md - Main documentation
    • FEATURES.md - Feature details
    • DEPLOYMENT.md - Deployment guides
    • CUSTOMIZATION.md - Customization options

Getting Help

  • Bug Reports: Open an issue on GitHub
  • Questions: Use GitHub Discussions
  • Documentation: Check the docs in this repository

Example Test PR

Create a PR with these characteristics to test spam detection:

Title: "Fix typo in README"

Body: "minor fix"

Changes: Change 1-2 lines in README.md

Expected Result:

  • Spam score: ~65-75
  • If threshold is 70: Should be flagged and closed
  • Check logs and /stats endpoint

Useful Commands

# View logs (Docker)
docker-compose logs -f pr-sentinel

# Restart service (Docker)
docker-compose restart

# Stop service (Docker)
docker-compose down

# Check stats
curl http://localhost:8000/stats | python -m json.tool

# Test webhook manually
curl -X POST http://localhost:8000/webhook \
  -H "Content-Type: application/json" \
  -H "X-GitHub-Event: pull_request" \
  -d @test_payload.json

# Run tests
python test_spam_detector.py

Success Checklist

  • Python/Docker installed
  • GitHub token created and configured
  • Dependencies installed
  • Server running and accessible
  • Health check returns OK
  • GitHub webhook configured
  • Test PR processed successfully
  • Stats show tracked PR
  • Logs show PR analysis

You're All Set! 🎉

PR-Sentinel is now protecting your repository from spam PRs!

Monitor the /stats endpoint and logs to see it in action.