PR Health Score Agent

A comprehensive CLI tool that analyzes GitHub Pull Requests and provides AI-powered health scores with automated recommendations.

🌟 Key Features

• Comprehensive 13-Category Scoring (100 points total)

  • PR Review Criteria (70 pts): Size, Tests, Commits, Reviews, Security, Code Quality, Dependencies, Documentation
  • AI-Powered Impact Analysis (30 pts): Complexity, Impact Scope, Performance

• AI-Powered Analysis with multiple providers:

  • Google Gemini (Recommended - Free tier available)
  • AWS Bedrock (Claude 3.5)
  • OpenAI GPT-4

• Automated Actions:

  • 💬 Post detailed health reports as PR comments
  • 🏷️ Auto-label PRs (health-check:pass/fail)
  • ✅ Create status checks for merge blocking
  • 📈 Provide actionable recommendations

• Security Scanning:

  • Uses GitHub Dependabot API (free, no GHAS license required)
  • Detects Critical, High, Moderate, and Low severity vulnerabilities
  • Supports 9+ ecosystems (npm, pip, maven, gradle, etc.)

📦 Installation

From PyPI (Recommended)

# Basic installation
pip install pr-health-agent

# With AWS Bedrock support
pip install pr-health-agent[bedrock]

# With all optional dependencies
pip install pr-health-agent[all]

🚀 Quick Start

1. Check Installation

pr-health --version

2. Set Environment Variables

Required:

export GITHUB_TOKEN="your_github_personal_access_token"

Optional (for AI analysis - choose one):

export GEMINI_API_KEY="your_gemini_api_key"        # Google Gemini
export BEDROCK_API_KEY="your_bedrock_api_key"      # AWS Bedrock
export OPENAI_API_KEY="your_openai_api_key"        # OpenAI

3. Run Analysis

Interactive Menu (Easiest):

pr-health-app

Setup Wizard:

pr-health-interactive

Direct Analysis:

# Basic analysis
pr-health owner/repo 123

# With AI analysis
pr-health owner/repo 123 --ai-analysis

# Full analysis with comments and labels
pr-health owner/repo 123 --ai-analysis --post-comment --add-labels

📊 Scoring System

Category	Points	What It Measures
PR Review	70
Size	5	Lines, files, commits
Test Quality	10	Coverage % and test files
Commit Quality	5	Conventional commits, messages
Review Quality	5	Reviewers, approvals, comments
Security	10	Vulnerability scanning
Code Quality	8	Complexity, duplication
Code Style	3	Linting, formatting
Dependencies	4	Vulnerability detection
CHANGELOG	5	Updates and versioning
CODEOWNERS	3	File coverage
Breaking Changes	5	Detection and documentation
Documentation	7	PR description quality
AI Impact	30
Complexity	10	Architectural complexity
Impact Scope	10	Business and technical impact
Performance	10	Resource usage implications

Score Categories

Score	Category	Merge Status
90-100	🌟 Excellent	✅ Recommended
80-89	✅ Good	✅ Recommended
70-79	⚠️ Needs Improvement	✅ Allowed
60-69	🔴 Poor	🚫 Blocked
0-59	🚫 Critical Issues	🚫 Blocked

🔧 Configuration

Create config.yaml to customize (optional - defaults provided):

thresholds:
  min_passing_score: 70
  excellent_score: 90

weights:
  size: 10
  commit_quality: 10
  test_quality: 20
  review_quality: 20
  complexity: 15
  security: 15
  code_quality: 5
  documentation: 5

🤖 GitHub Actions Integration

Add to .github/workflows/pr-health.yml:

name: PR Health Check

on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  health-check:
    runs-on: ubuntu-latest
    steps:
      - name: Install PR Health Agent
        run: pip install pr-health-agent

      - name: Run Health Check
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
        run: |
          pr-health ${{ github.repository }} ${{ github.event.pull_request.number }} \
            --ai-analysis \
            --post-comment \
            --add-labels \
            --add-status

📋 Prerequisites

• Python 3.8+
• GitHub Personal Access Token with scopes:
  • repo (Full repository access)
  • security_events (For vulnerability scanning)
• AI Provider API Key (Optional):
  • Google Gemini - Free tier available
  • AWS Bedrock - Pay as you go
  • OpenAI - Pay as you go

📚 Documentation

• Installation Guide - Detailed installation instructions
• AI Providers Setup - Configure AI analysis
• Quick Reference - Command cheat sheet
• Advanced Features - Customization and advanced usage

💡 Usage Examples

Analyze with custom threshold:

pr-health owner/repo 123 --threshold 80

JSON output:

pr-health owner/repo 123 --output json

Custom config:

pr-health owner/repo 123 --config custom.yaml

Verbose mode:

pr-health owner/repo 123 --ai-analysis --verbose

🆘 Troubleshooting

"GITHUB_TOKEN not found"

export GITHUB_TOKEN="your_token_here"

"Permission denied"

• Ensure token has repo and security_events scopes

"AI analysis failed"

export GEMINI_API_KEY="your_gemini_key"

Check version:

pr-health --version

🔗 Commands

Command	Purpose
pr-health	Analyze specific PR
pr-health-app	Interactive menu
pr-health-interactive	Setup wizard

All commands support --version and --help flags.

📄 License

MIT License

🤝 Contributing

Contributions welcome! Please check the contributing guidelines.

---

Latest Version: 2.0.5

Quick Install: pip install pr-health-agent

Quick Start: pr-health-app