{"repo": "amarkdotdev/patchpulse", "files": {"README.md": {"61c82cccb81af280a0e23d9cf5a9d648fd1bea61": {"t": 1785746437.7308464, "n": 28211, "h": "c97e9618143b0fb5", "c": "# PatchPulse\n\n<div align=\"center\">\n\n**🔓 100% Open Source | 🤖 Bring Your Own LLM | 🚀 Self-Hosted Kubernetes Risk Analysis**\n\n[![License](https://img.shields.io/badge/license-Non--Commercial-blue.svg)](LICENSE)\n[![Website](https://img.shields.io/badge/website-patchpulse.dev-blue)](https://patchpulse.dev)\n[![Buy Me a Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-☕-yellow)](https://buymeacoffee.com/aaronmark)\n\n**Stop preventable production incidents before they happen**\n\n[Quick Start](#-quick-start) • [How It Works](#-how-patchpulse-works) • [Features](#-key-features) • [Support](#-need-help)\n\n</div>\n\n---\n\n## 🎯 What is PatchPulse?\n\nAfter one too many 3am pages from production incidents that could've been caught earlier, I built PatchPulse. It's a self-hosted tool that analyzes your Kubernetes changes before they hit production, combining rule-based guardrails with optional AI analysis to give you explainable risk scores.\n\nThink of it as a safety net for your deployments - it catches the stuff that slips through code review and CI/CD checks.\n\n### Why I Built This\n\nI've been there - you merge a PR, deploy to production, and suddenly pods are OOMKilled because someone forgot resource limits. Or worse, a security misconfiguration opens up your cluster. PatchPulse catches these issues before they become incidents.\n\n- **🛡️ Catch Problems Early**: See risky changes before they reach production\n- **🔍 Understand Why**: Get clear explanations when something's flagged\n- **🤖 Optional AI**: Use AI for deeper analysis, or skip it entirely - your call\n- **⚡ Real-Time Alerts**: Know immediately when something's wrong\n- **🔓 100% Open Source**: No vendor lock-in, no SaaS fees, just code you can trust\n- **🏠 Your Data, Your Control**: Everything runs on your infrastructure\n\n---\n\n## ✨ Key Features\n\n### Core Capabilities\n\n- **🔓 Fully Open Source** - Non-commercial license, no vendor lock-in\n- **🤖 Bring Your Own LLM** - Use OpenAI, DeepSeek, Claude, Gemini, or any OpenAI-compatible API\n- **🏠 Self-Hosted** - Your data stays on your infrastructure\n- **🛡️ 11+ Guardrails** - Rule-based checks for Kubernetes best practices\n- **🧠 AI-Powered Analysis** - Security scanning, recommendations, incident prediction\n- **⚡ Real-Time** - WebSocket updates and instant notifications\n- **🔌 Integrations** - GitHub, GitLab, Slack, Teams, PagerDuty, Email\n- **📊 Enterprise Features** - Admission webhooks, policy bundles, SBOM verification, multi-tenancy\n\n### Guardrails Included\n\n1. **Resource Limits** - Ensures CPU/memory limits are set\n2. **Resource Requests** - Validates resource requests are configured\n3. **Readiness Probes** - Checks for readiness probe configuration\n4. **Liveness Probes** - Validates liveness probe setup\n5. **Security Context** - Enforces security context settings\n6. **Image Tags** - Prevents `latest` tag usage\n7. **Namespace Validation** - Ensures proper namespace usage\n8. **Service Account** - Validates service account configuration\n9. **Network Policies** - Checks network policy compliance\n10. **Resource Quotas** - Validates resource quota adherence\n11. **Pod Disruption Budgets** - Ensures PDB configuration\n\n---\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- **Docker** (running) - Required for containerized deployment\n- **Python 3.11+** - For local development\n- **Go 1.21+** - For agent development (optional)\n- **kubectl** - For Kubernetes integration (optional)\n\n### Installation Steps\n\n#### 1. Clone the Repository\n\n```bash\ngit clone https://github.com/amarkdotdev/patchpulse.git\ncd patchpulse\n```\n\n#### 2. Configure Your LLM Provider (Optional)\n\nPatchPulse supports multiple AI providers. **You only need to provide an API key for ONE provider:**\n\n```bash\n# Create .env file\ntouch .env\n\n# Option 1: OpenAI (recommended for best results)\necho \"OPENAI_API_KEY=sk-your-key-here\" >> .env\n\n# Option 2: DeepSeek (cost-effective alternative)\n# echo \"DEEPSEEK_API_KEY=sk-your-key-here\" >> .env\n\n# Option 3: Claude (Anthropic)\n# echo \"ANTHROPIC_API_KEY=sk-ant-your-key-here\" >> .env\n# Note: Requires: pip install anthropic\n\n# Option 4: Google Gemini\n# echo \"GEMINI_API_KEY=your-key-here\" >> .env\n# Note: Requires: pip install google-generativeai\n\n# Optionally specify which provider to use (defaults to first available)\n# echo \"AI_PROVIDER=openai\" >> .env\n```\n\n**💡 No LLM? No Problem!** PatchPulse works perfectly fine without any AI - you'll still get all the rule-based guardrails and risk scoring. The AI stuff is just extra if you want it.\n\n#### 3. Start PatchPulse\n\n```bash\n# Start all services\ndocker compose up -d\n\n# Check logs\ndocker compose logs -f backend\n\n# Wait for services to be ready (about 10-15 seconds)\n```\n\n#### 4. Access the Application\n\nOnce PatchPulse is running, access it at:\n\n- **Dashboard**: http://localhost:8000/dashboard\n  - Main user interface for monitoring decisions, viewing analytics, and managing configurations\n  - Real-time updates via WebSocket\n  - Risk visualization and decision history\n\n- **API Documentation**: http://localhost:8000/docs\n  - Interactive Swagger/OpenAPI documentation\n  - Test API endpoints directly from the browser\n  - Full API reference\n\n- **Health Check**: http://localhost:8000/health\n  - Service health status\n  - Database connectivity check\n\n- **API Root**: http://localhost:8000/api\n  - API information and available endpoints\n\n#### 5. Start Using PatchPulse\n\n1. **Access the Dashboard**: Open http://localhost:8000/dashboard in your browser\n2. **View Decisions**: See real-time risk analysis and decisions\n3. **Configure Integrations**: Set up GitHub, GitLab, Slack, or other integrations via the API\n4. **Monitor Analytics**: Track risk trends, blocked changes, and system health\n\n**Note**: The dashboard is the main interface for PatchPulse. The website (patchpulse.dev) is a separate marketing site and not part of this repository.\n\n---\n\n## 🔄 How PatchPulse Works\n\n### Deployment Models\n\nPatchPulse can be deployed in two ways:\n\n#### Option 1: Standalone Mode (Recommended for Getting Started)\n\n**Backend runs separately** (Docker Compose, VM, or anywhere):\n- Backend service runs independently\n- Agent runs **outside** your Kubernetes cluster\n- Agent connects to your cluster using `kubeconfig`\n- Best for: Testing, development, or when you don't want to deploy into your cluster\n\n```bash\n# 1. Start backend (runs anywhere)\ndocker compose up -d\n\n# 2. Run agent locally (connects to your cluster via kubeconfig)\ncd app/agent\nexport BACKEND_URL=http://localhost:8000\nexport KUBECONFIG=$HOME/.kube/config  # Points to your cluster\ngo run cmd/agent/main.go\n```\n\n#### Option 2: In-Cluster Mode (Production)\n\n**Both backend and agent run inside Kubernetes**:\n- Backend deployed as a Kubernetes Deployment\n- Agent deployed in the same or different namespace\n- Agent uses in-cluster config (ServiceAccount)\n- Best for: Production deployments, full integration\n\n```bash\n# Deploy both backend and agent to your cluster\nhelm install patchpulse-backend ./helm/backend --namespace patchpulse\nhelm install patchpulse-agent ./helm/agent --namespace patchpulse\n```\n\n### How It Analyzes Your Changes\n\nPatchPulse works in **two ways**:\n\n#### 1. **Git Integration** (Pre-Deployment Analysis)\n- Monitors GitHub/GitLab PRs/MRs\n- Analyzes Kubernetes manifests in diffs\n- Evaluates guardrails **before** code is merged\n- Sends notifications if risky changes detected\n\n```bash\n# Example: PR with risky deployment.yaml\n# PatchPulse detects: \"Missing resource limits\"\n# → Risk score: 50\n# → Decision: Advisory (allows, but warns)\n```\n\n#### 2. **Cluster Monitoring** (Post-Deployment)\n- Agent watches your Kubernetes cluster\n- Collects deployment signals, pod events, node status\n- Detects issues in running workloads\n- Provides real-time cluster health insights\n\n### Complete Workflow\n\n```\n┌─────────────────┐\n│  Developer      │\n│  Creates PR     │\n└────────┬────────┘\n         │\n         ▼\n┌─────────────────┐     ┌──────────────────┐\n│  Git Integration│────▶│  PatchPulse      │\n│  (GitHub/GitLab)│     │  Backend         │\n└─────────────────┘     │  (FastAPI)       │\n                        └────────┬─────────┘\n                                 │\n                        ┌────────▼─────────┐\n                        │  Policy Engine   │\n                        │  + AI Analysis   │\n                        └────────┬─────────┘\n                                 │\n                        ┌────────▼─────────┐\n                        │  Risk Score      │\n                        │  Decision        │\n                        └────────┬─────────┘\n                                 │\n         ┌───────────────────────┼───────────────────────┐\n         │                       │                       │\n         ▼                       ▼                       ▼\n┌─────────────────┐    ┌─────────────────┐   ┌─────────────────┐\n│  Notification   │    │  Dashboard       │   │  Kubernetes     │\n│  (Slack/Email)  │    │  (Web UI)        │   │  Agent          │\n└─────────────────┘    └─────────────────┘   └────────┬────────┘\n                                                       │\n                                                       ▼\n                                              ┌─────────────────┐\n                                              │  Your K8s       │\n                                              │  Cluster        │\n                                              └─────────────────┘\n```\n\n### Connecting to Your Kubernetes Cluster\n\n#### For Standalone Mode:\n\n1. **Ensure you have access to your cluster:**\n```bash\n# Test cluster access\nkubectl get nodes\n\n# If using a remote cluster, make sure kubeconfig is set\nexport KUBECONFIG=$HOME/.kube/config\n```\n\n2. **Start the agent pointing to your cluster:**\n```bash\n# The agent will automatically use your kubeconfig\nexport BACKEND_URL=http://localhost:8000  # Where backend is running\ncd app/agent\ngo run cmd/agent/main.go\n```\n\n#### For In-Cluster Mode:\n\n1. **Deploy PatchPulse to your cluster:**\n```bash\n# Create namespace\nkubectl create namespace patchpulse\n\n# Deploy backend\nhelm install patchpulse-backend ./helm/backend \\\n  --namespace patchpulse \\\n  --set env.DATABASE_URL=\"postgresql://...\"\n\n# Deploy agent (automatically connects to cluster)\nhelm install patchpulse-agent ./helm/agent \\\n  --namespace patchpulse \\\n  --set env.BACKEND_URL=\"http://patchpulse-backend:8000\"\n```\n\n2. **The agent automatically uses in-cluster config** (no kubeconfig needed)\n\n### What Gets Analyzed?\n\n#### From Git (PR/MR Analysis):\n- Kubernetes manifests (Deployments, Services, ConfigMaps, etc.)\n- Changes to resource limits, requests, probes\n- Security context changes\n- Image tag updates\n- Network policy changes\n\n#### From Cluster (Agent Monitoring):\n- Deployment availability and replica counts\n- Pod restart counts\n- Node readiness status\n- Warning events\n- Resource utilization trends\n\n---\n\n## 📖 Table of Contents\n\n- [Architecture](#-architecture)\n- [Configuration](#-configuration)\n- [LLM Provider Setup](#-llm-provider-setup)\n- [API Usage](#-api-usage)\n- [Deployment](#-deployment)\n- [Development](#-development)\n- [Use Cases](#-use-cases)\n- [Contributing](#-contributing)\n- [Support](#-support)\n- [License](#-license)\n\n---\n\n## 🏗️ Architecture\n\n### Components\n\n#### 1. Backend (FastAPI)\n- REST API for change events and decisions\n- Policy engine with 11+ guardrails\n- AI-powered risk analysis (bring your own LLM!)\n- PostgreSQL database for persistence\n- WebSocket support for real-time updates\n\n#### 2. Agent (Go)\n- Kubernetes cluster monitoring\n- Resource snapshotting\n- Event watching\n- Least-privilege RBAC\n\n#### 3. Git Integrations\n- GitHub PR analysis\n- GitLab MR analysis\n- Diff parsing and manifest extraction\n\n#### 4. Notification Integrations\n- Slack notifications with interactive approval buttons\n- Email notifications\n- Microsoft Teams integration\n- PagerDuty integration\n\n#### 5. Dashboard UI (Primary Interface)\n- Real-time decision monitoring via WebSocket\n- Risk visualization and analytics\n- Decision history and filtering\n- Export functionality (CSV/JSON)\n- Accessible at `/dashboard` endpoint\n\n### Data Flow\n\n```\n1. Developer creates PR/MR → Git integration detects change\n2. Change event sent to backend → Policy engine evaluates\n3. AI analysis runs (if configured) → Security scan, recommendations, predictions\n4. Risk score calculated (0-100) → Decision made (allow/block)\n5. Notification sent to Slack/Teams → Decision stored in database\n6. Dashboard updates in real-time via WebSocket\n```\n\n### System Architecture Diagram\n\n```\n┌─────────────┐     ┌──────────────┐     ┌─────────────┐\n│   GitHub    │────▶│ Git Poller   │────▶│  Backend    │\n│   GitLab    │     │              │     │  (FastAPI)  │\n└─────────────┘     └──────────────┘     └──────┬──────┘\n                                                 │\n┌─────────────┐     ┌──────────────┐             │\n│ Kubernetes  │────▶│   Agent     │─────────────┘\n│   Cluster   │     │    (Go)     │\n└─────────────┘     └──────────────┘\n                                                 │\n┌─────────────┐     ┌──────────────┐     ┌─────▼──────┐\n│   Slack     │◀────│ Notifications│◀────│ PostgreSQL │\n│   Teams     │     │              │     │  Database  │\n│  PagerDuty  │     └──────────────┘     └────────────┘\n│   Email     │\n└─────────────┘\n```\n\n---\n\n## 🔧 Configuration\n\n### Environment Variables\n\nCreate a `.env` file in the root directory:\n\n```bash\n# Database\nDATABASE_URL=postgresql://patchpulse:patchpulse@postgres:5432/patchpulse\n\n# Policy Mode (advisory or enforce)\nPOLICY_MODE=advisory\n\n# Logging\nLOG_LEVEL=INFO\n\n# AI Provider - Choose ONE (see LLM Provider Setup section)\nOPENAI_API_KEY=your_openai_api_key\n# OR\n# DEEPSEEK_API_KEY=your_deepseek_api_key\n# OR\n# ANTHROPIC_API_KEY=your_anthropic_api_key\n# OR\n# GEMINI_API_KEY=your_gemini_api_key\n\n# Optional: Specify which provider to use (defaults to first available)\nAI_PROVIDER=openai\n\n# Git Integration\nGITHUB_TOKEN=your_github_token\nGITHUB_REPOS=owner/repo1,owner/repo2\nGITLAB_TOKEN=your_gitlab_token\nGITLAB_PROJECTS=12345,67890\n\n# JWT Secret (auto-generated if not set)\nJWT_SECRET_KEY=your_jwt_secret\n```\n\n### Policy Modes\n\n- **`advisory`**: Logs decisions but doesn't block changes (default)\n  - Best for: Testing, gradual rollout, learning mode\n  - All decisions are logged and visible in dashboard\n  - No changes are blocked\n\n- **`enforce`**: Blocks high-risk changes (score ≥ 70)\n  - Best for: Production environments\n  - High-risk changes are automatically blocked\n  - Requires manual approval for blocked changes\n\n---\n\n## 🤖 LLM Provider Setup\n\nPatchPulse is **100% open source** and supports **bring your own LLM**. You can use any of these providers:\n\n### Supported Providers\n\n| Provider | Cost | Quality | Setup |\n|----------|------|---------|-------|\n| **OpenAI** | $$$ | ⭐⭐⭐⭐⭐ | `OPENAI_API_KEY=sk-...` |\n| **DeepSeek** | $ | ⭐⭐⭐⭐ | `DEEPSEEK_API_KEY=sk-...` |\n| **Claude** | $$$ | ⭐⭐⭐⭐⭐ | `ANTHROPIC_API_KEY=sk-ant-...` |\n| **Gemini** | $$ | ⭐⭐⭐⭐ | `GEMINI_API_KEY=...` |\n\n### OpenAI\n\n```bash\nexport OPENAI_API_KEY=sk-your-key-here\n# Or in .env file:\necho \"OPENAI_API_KEY=sk-your-key-here\" >> .env\n```\n\n**Models**: Uses `gpt-4o-mini` by default (cost-effective). You can modify `ai_analyzer.py` to use other models.\n\n### DeepSeek (Recommended for Cost-Conscious Users)\n\n```bash\nexport DEEPSEEK_API_KEY=sk-your-key-here\n# Or in .env file:\necho \"DEEPSEEK_API_KEY=sk-your-key-here\" >> .env\n```\n\n**Models**: Uses `deepseek-chat` by default. OpenAI-compatible API.\n\n### Claude (Anthropic)\n\n```bash\n# First install the package\npip install anthropic\n\nexport ANTHROPIC_API_KEY=sk-ant-your-key-here\n# Or in .env file:\necho \"ANTHROPIC_API_KEY=sk-ant-your-key-here\" >> .env\n```\n\n**Models**: Uses `claude-3-5-sonnet-20241022` by default.\n\n### Google Gemini\n\n```bash\n# First install the package\npip install google-generativeai\n\nexport GEMINI_API_KEY=your-key-here\n# Or in .env file:\necho \"GEMINI_API_KEY=your-key-here\" >> .env\n```\n\n**Models**: Uses `gemini-1.5-pro` by default.\n\n### Using a Custom OpenAI-Compatible API\n\nPatchPulse supports any OpenAI-compatible API endpoint (Ollama, LocalAI, vLLM, etc.):\n\n```bash\n# Set a dummy API key (not used for local endpoints)\nexport OPENAI_API_KEY=not-used\n\n# Set your custom endpoint\nexport OPENAI_BASE_URL=http://localhost:11434/v1  # Ollama example\n# Or\nexport OPENAI_BASE_URL=http://localhost:8080/v1   # LocalAI example\n\n# Or in .env file:\necho \"OPENAI_API_KEY=not-used\" >> .env\necho \"OPENAI_BASE_URL=http://localhost:11434/v1\" >> .env\n```\n\n**Examples:**\n- **Ollama**: `OPENAI_BASE_URL=http://localhost:11434/v1`\n- **LocalAI**: `OPENAI_BASE_URL=http://localhost:8080/v1`\n- **vLLM**: `OPENAI_BASE_URL=http://localhost:8000/v1`\n- **Any OpenAI-compatible service**: Just set the base URL!\n\nThe system will automatically use your custom endpoint with the OpenAI client.\n\n### No LLM Required\n\n**PatchPulse works perfectly without any LLM!** If no API key is provided:\n- ✅ All rule-based guardrails work\n- ✅ Risk scoring works\n- ✅ All integrations work\n- ✅ Dashboard works\n- ⚠️ AI-powered features are disabled (security scanning, recommendations, predictions)\n\n---\n\n## 📊 API Usage\n\n### Create Change Event\n\n```bash\ncurl -X POST http://localhost:8000/api/v1/change-events \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"source\": \"github\",\n    \"repo\": \"org/repo\",\n    \"sha\": \"abc123\",\n    \"pr_number\": 42,\n    \"branch\": \"feature-branch\",\n    \"files\": [\"k8s/deployment.yaml\"],\n    \"diff_hunks\": [{\n      \"file\": \"k8s/deployment.yaml\",\n      \"hunk\": \"- limits:\\n  cpu: 500m\"\n    }],\n    \"timestamp\": \"2026-01-01T00:00:00Z\"\n  }'\n```\n\n### Get Decisions\n\n```bash\ncurl http://localhost:8000/api/v1/decisions?limit=10\n```\n\n### Get Analytics\n\n```bash\ncurl http://localhost:8000/api/v1/analytics/summary\n```\n\n### Get Decision by ID\n\n```bash\ncurl http://localhost:8000/api/v1/decisions/{decision_id}\n```\n\n### Filter Decisions\n\n```bash\n# Filter by risk score\ncurl \"http://localhost:8000/api/v1/decisions?min_risk=50&max_risk=100\"\n\n# Filter by source\ncurl \"http://localhost:8000/api/v1/decisions?source=github\"\n\n# Filter by date range\ncurl \"http://localhost:8000/api/v1/decisions?start_date=2026-01-01&end_date=2026-01-31\"\n```\n\nSee `/docs` for interactive API documentation.\n\n---\n\n## 🚢 Deployment\n\n### Docker Compose (Recommended for Quick Start)\n\n```bash\ndocker compose up -d\n```\n\n### Kubernetes (Helm)\n\n**Option 1: Using your `.env` file (Recommended)**\n\n```bash\n# Create a values file from your .env\n# This reads your .env file and creates Helm values\ncat > /tmp/patchpulse-values.yaml <<EOF\nenv:\n  DATABASE_URL: \"postgresql://patchpulse:patchpulse@postgres:5432/patchpulse\"\n  POLICY_MODE: \"advisory\"\n  LOG_LEVEL: \"INFO\"\n  OPENAI_API_KEY: \"$(grep OPENAI_API_KEY .env | cut -d '=' -f2)\"\n  DEEPSEEK_API_KEY: \"$(grep DEEPSEEK_API_KEY .env | cut -d '=' -f2 || echo '')\"\n  ANTHROPIC_API_KEY: \"$(grep ANTHROPIC_API_KEY .env | cut -d '=' -f2 || echo '')\"\n  GEMINI_API_KEY: \"$(grep GEMINI_API_KEY .env | cut -d '=' -f2 || echo '')\"\nEOF\n\n# Install backend using values from .env\nhelm install patchpulse-backend ./helm/backend \\\n  --namespace patchpulse \\\n  --create-namespace \\\n  --values /tmp/patchpulse-values.yaml\n\n# Install agent\nhelm install patchpulse-agent ./helm/agent \\\n  --namespace patchpulse \\\n  --set env.BACKEND_URL=http://patchpulse-backend:8000\n```\n\n**Option 2: Using --set-file (Alternative)**\n\n```bash\n# Install backend with API key from .env file\nhelm install patchpulse-backend ./helm/backend \\\n  --namespace patchpulse \\\n  --create-namespace \\\n  --set env.OPENAI_API_KEY=\"$(grep OPENAI_API_KEY .env | cut -d '=' -f2)\" \\\n  --set env.POLICY_MODE=advisory\n\n# Install agent\nhelm install patchpulse-agent ./helm/agent \\\n  --namespace patchpulse \\\n  --set env.BACKEND_URL=http://patchpulse-backend:8000\n```\n\n**Option 3: Manual values override**\n\nEdit `helm/backend/values.yaml` and add your API keys to the `env` section, then install:\n\n```bash\nhelm install patchpulse-backend ./helm/backend \\\n  --namespace patchpulse \\\n  --create-namespace\n```\n\n### Production Considerations\n\n- Use environment variables for secrets (never hardcode)\n- Set up proper TLS/SSL certificates\n- Configure database backups\n- Set up monitoring and alerting\n- Use a managed PostgreSQL database for production\n- Configure rate limiting\n- Set up log aggregation\n- Enable audit logging\n\n---\n\n## 🛠️ Development\n\n### Local Development Setup\n\n```bash\n# Backend\ncd app/backend\npython -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\npip install -r requirements.txt\nuvicorn main:app --reload\n\n# Agent\ncd app/agent\ngo run cmd/agent/main.go\n\n# Git Integration\ncd app/integrations/git\npython poller.py\n```\n\n### Running Tests\n\n```bash\n# Unit tests\ncd app/backend\npytest tests/\n\n# Integration tests\ndocker compose up -d\n./test_api_endpoints.sh\n```\n\n### Project Structure\n\n```\npatchpulse/\n├── app/                    # Application code\n│   ├── backend/           # FastAPI backend service\n│   │   ├── main.py        # Main application entry point\n│   │   ├── models.py      # Pydantic models and SQLAlchemy ORM\n│   │   ├── database.py    # Database connection and setup\n│   │   ├── policy_engine.py # Policy evaluation and guardrails\n│   │   ├── ai_analyzer.py # AI-powered risk analysis (BYO LLM!)\n│   │   ├── ai_features.py # Advanced AI features\n│   │   ├── auth.py        # Authentication system\n│   │   └── requirements.txt\n│   ├── agent/             # Kubernetes agent (Go)\n│   │   ├── cmd/agent/     # Agent main application\n│   │   └── Dockerfile\n│   ├── integrations/     # External integrations\n│   │   ├── git/           # GitHub/GitLab integration\n│   │   ├── slack/         # Slack notifications\n│   │   ├── teams/         # Microsoft Teams integration\n│   │   ├── pagerduty/     # PagerDuty integration\n│   │   └── email/         # Email notifications\n│   └── ui/                # Dashboard UI (served at /dashboard)\n├── docs/                  # Technical documentation\n├── helm/                  # Kubernetes Helm charts\n├── docker-compose.yml     # Local development setup\n└── README.md             # This file\n```\n\n---\n\n## 💼 Use Cases\n\n### 1. CI/CD Pipeline Integration\n\nIntegrate PatchPulse into your CI/CD pipeline to automatically analyze PRs:\n\n```yaml\n# GitHub Actions example\n- name: Analyze with PatchPulse\n  run: |\n    curl -X POST $PATCHPULSE_URL/api/v1/change-events \\\n      -H \"Content-Type: application/json\" \\\n      -d @change-event.json\n```\n\n### 2. Pre-Deployment Validation\n\nValidate Kubernetes manifests before deployment:\n\n```bash\n# Analyze deployment manifests\nkubectl apply --dry-run=client -f deployment.yaml | \\\n  patchpulse analyze --source=manual\n```\n\n### 3. Compliance Auditing\n\nTrack compliance with Kubernetes best practices:\n\n```bash\n# Get compliance report\ncurl http://localhost:8000/api/v1/analytics/compliance\n```\n\n### 4. Incident Prevention\n\nPrevent production incidents by catching risky changes:\n\n- Missing resource limits\n- Security misconfigurations\n- Image tag issues\n- Network policy violations\n\n### 5. Team Education\n\nUse PatchPulse to educate teams on Kubernetes best practices:\n\n- Real-time feedback on PRs\n- Detailed explanations of guardrail violations\n- Historical analytics on common mistakes\n\n---\n\n## 🛡️ Security\n\n- **API keys never exposed** in logs or responses\n- **Least-privilege RBAC** for agent\n- **Encrypted database** connections\n- **TLS** for all API communications\n- **Audit logging** for all decisions\n- **Rate limiting** on API endpoints\n- **Self-hosted** - your data stays on your infrastructure\n\nSee [SECURITY.md](SECURITY.md) for detailed security information.\n\n---\n\n## 🤝 Contributing\n\nContributions are welcome! This is a solo project, so any help is genuinely appreciated.\n\n1. Fork the repo\n2. Create a branch (`git checkout -b feature/your-feature`)\n3. Make your changes\n4. Commit (`git commit -m 'Add your feature'`)\n5. Push (`git push origin feature/your-feature`)\n6. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for more details.\n\n**What I'd love help with:**\n- 🐛 Bug fixes (especially edge cases I haven't hit yet)\n- ✨ New features (if you have ideas, open an issue first to discuss)\n- 📚 Documentation (I'm not great at writing docs, so improvements are welcome)\n- 🧪 Tests (more test coverage is always good)\n- 🎨 UI improvements (the dashboard could definitely be prettier)\n- 🔌 New integrations (want to add something? Let's talk)\n\n---\n\n## 📄 License\n\nThis project is licensed under the **PatchPulse Non-Commercial License** - see the [LICENSE](LICENSE) file for details.\n\n**✅ Permitted Uses:**\n- Personal use\n- Educational use\n- Research and development\n- Internal use within non-profit organizations\n- Contributing to the PatchPulse project\n- Forking and modifying for personal/educational purposes\n\n**❌ Prohibited Uses:**\n- Commercial use (selling, licensing, or providing as a service)\n- Use in commercial products or services\n- Reselling or redistributing for profit\n- Use by for-profit companies without explicit written permission\n\n**💼 Commercial Licensing:**\nFor commercial use, please contact us to obtain a commercial license. Commercial licenses are available for:\n- SaaS providers\n- Enterprise deployments\n- Commercial products incorporating PatchPulse\n- Consulting services using PatchPulse\n\n**Contact:** amarkdotdev@gmail.com\n\nThis license protects the open-source nature of PatchPulse while ensuring commercial use requires proper licensing.\n\n---\n\n## 🆘 Need Help?\n\n**Documentation**: http://localhost:8000/docs (when running locally)  \n**Website**: https://patchpulse.dev  \n**Issues**: https://github.com/amarkdotdev/patchpulse/issues  \n**Email**: amarkdotdev@gmail.com\n\n**Ways to help:**\n- 🐛 Found a bug? Open an issue - I'll try to fix it\n- 💡 Have an idea? Open a discussion or issue\n- 📖 Docs unclear? Send a PR to improve them\n\n---\n\n## ☕ Support the Project\n\nIf PatchPulse has saved you from a late-night incident or just made your life easier, consider buying me a coffee:\n\n**[☕ Buy Me a Coffee](https://buymeacoffee.com/aaronmark)**\n\nIt's not required at all, but it's a nice way to say thanks and helps me justify spending more time on this project. Every bit helps! 🙏\n\n---\n\n## 🎯 Roadmap\n\n- [ ] Multi-tenant support (in progress)\n- [ ] Custom guardrail DSL\n- [ ] Integration with more Git providers (Bitbucket, Azure DevOps)\n- [ ] Additional AI provider support\n- [ ] Compliance reporting (SOC2, ISO27001)\n- [ ] Enhanced documentation\n- [ ] Local LLM support (Ollama, LocalAI)\n- [ ] Webhook support for real-time PR analysis\n- [ ] Custom risk scoring algorithms\n- [ ] Policy templates library\n\n---\n\n## 👨‍💻 Hey, I'm Aaron\n\nI'm a DevOps engineer based in Israel 🇮🇱, and I built PatchPulse because I was tired of preventable production incidents. \n\nYou know those moments when you're debugging at 2am and think \"we should've caught this earlier\"? That's what PatchPulse is for. It's the tool I wish I had when I was managing Kubernetes clusters at scale.\n\nI built this in my spare time, iterating based on real problems I've faced. It's not perfect, but it's useful, and I'm sharing it because I think other teams might find it helpful too.\n\n**Want to chat?**\n- 📧 Email: amarkdotdev@gmail.com\n- 🐙 GitHub: [@amarkdotdev](https://github.com/amarkdotdev)\n- ☕ Buy Me a Coffee: [buymeacoffee.com/aaronmark](https://buymeacoffee.com/aaronmark) (if PatchPulse saves you from a late-night incident, consider it 😊)\n\n---\n\n## 🙏 Thanks\n\nThis project wouldn't exist without the open source community. Special shoutout to everyone who's contributed, reported bugs, or just used PatchPulse and gave feedback.\n\nBuilt with:\n- **FastAPI** - Because Python web frameworks don't have to be slow\n- **PostgreSQL** - Reliable and battle-tested\n- **Go** - For the Kubernetes agent (because sometimes you need speed)\n- **Docker** - Makes deployment actually bearable\n- **Kubernetes** - The thing we're all trying to make safer\n\n---\n\n<div align=\"center\">\n\n**🔓 Open Source | 🤖 Bring Your Own LLM | 🚀 Self-Hosted**\n\n**Made with ❤️ in Israel for the Kubernetes community worldwide**\n\n[⭐ Star on GitHub](https://github.com/amarkdotdev/patchpulse) • [📖 Documentation](https://patchpulse.dev) • [☕ Buy Me a Coffee](https://buymeacoffee.com/aaronmark) • [🐛 Report Bug](https://github.com/amarkdotdev/patchpulse/issues)\n\n</div>\n"}, "ecf8237de8ad4765c52f1d721fd030308e32a0b9": {"t": 1785764229.1281633, "n": 28412, "h": "e3a7b1b9478a9390", "c": "# PatchPulse\n\n<div align=\"center\">\n\n**🔓 100% Open Source | 🤖 Bring Your Own LLM | 🚀 Self-Hosted Kubernetes Risk Analysis**\n\n[![License](https://img.shields.io/badge/license-Non--Commercial-blue.svg)](LICENSE)\n[![GitHub stars](https://img.shields.io/github/stars/amarkdotdev/patchpulse?style=social)](https://github.com/amarkdotdev/patchpulse)\n[![Website](https://img.shields.io/badge/website-patchpulse.dev-blue)](https://patchpulse.dev)\n[![Buy Me a Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-☕-yellow)](https://buymeacoffee.com/aaronmark)\n\n**Stop preventable production incidents before they happen**\n\n[Quick Start](#-quick-start) • [How It Works](#-how-patchpulse-works) • [Features](#-key-features) • [Support](#-need-help)\n\n</div>\n\n---\n\n## 🎯 What is PatchPulse?\n\nAfter one too many 3am pages from production incidents that could've been caught earlier, I built PatchPulse. It's a self-hosted tool that analyzes your Kubernetes changes before they hit production, combining rule-based guardrails with optional AI analysis to give you explainable risk scores.\n\nThink of it as a safety net for your deployments - it catches the stuff that slips through code review and CI/CD checks.\n\n### Why I Built This\n\nI've been there - you merge a PR, deploy to production, and suddenly pods are OOMKilled because someone forgot resource limits. Or worse, a security misconfiguration opens up your cluster. PatchPulse catches these issues before they become incidents.\n\n- **🛡️ Catch Problems Early**: See risky changes before they reach production\n- **🔍 Understand Why**: Get clear explanations when something's flagged\n- **🤖 Optional AI**: Use AI for deeper analysis, or skip it entirely - your call\n- **⚡ Real-Time Alerts**: Know immediately when something's wrong\n- **🔓 100% Open Source**: No vendor lock-in, no SaaS fees, just code you can trust\n- **🏠 Your Data, Your Control**: Everything runs on your infrastructure\n\n---\n\n## ✨ Key Features\n\n### Core Capabilities\n\n- **🔓 Fully Open Source** - Non-commercial license, no vendor lock-in\n- **🤖 Bring Your Own LLM** - Use OpenAI, DeepSeek, Claude, Gemini, or any OpenAI-compatible API\n- **🏠 Self-Hosted** - Your data stays on your infrastructure\n- **🛡️ 11+ Guardrails** - Rule-based checks for Kubernetes best practices\n- **🧠 AI-Powered Analysis** - Security scanning, recommendations, incident prediction\n- **⚡ Real-Time** - WebSocket updates and instant notifications\n- **🔌 Integrations** - GitHub, GitLab, Slack, Teams, PagerDuty, Email\n- **📊 Enterprise Features** - Admission webhooks, policy bundles, SBOM verification, multi-tenancy\n\n### Guardrails Included\n\n1. **Resource Limits** - Ensures CPU/memory limits are set\n2. **Resource Requests** - Validates resource requests are configured\n3. **Readiness Probes** - Checks for readiness probe configuration\n4. **Liveness Probes** - Validates liveness probe setup\n5. **Security Context** - Enforces security context settings\n6. **Image Tags** - Prevents `latest` tag usage\n7. **Namespace Validation** - Ensures proper namespace usage\n8. **Service Account** - Validates service account configuration\n9. **Network Policies** - Checks network policy compliance\n10. **Resource Quotas** - Validates resource quota adherence\n11. **Pod Disruption Budgets** - Ensures PDB configuration\n\n---\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- **Docker** (running) - Required for containerized deployment\n- **Python 3.11+** - For local development\n- **Go 1.21+** - For agent development (optional)\n- **kubectl** - For Kubernetes integration (optional)\n\n### Installation Steps\n\n#### 1. Clone the Repository\n\n```bash\ngit clone https://github.com/amarkdotdev/patchpulse.git\ncd patchpulse\n```\n\n#### 2. Configure Your LLM Provider (Optional)\n\nPatchPulse supports multiple AI providers. **You only need to provide an API key for ONE provider:**\n\n```bash\n# Create .env file\ntouch .env\n\n# Option 1: OpenAI (recommended for best results)\necho \"OPENAI_API_KEY=sk-your-key-here\" >> .env\n\n# Option 2: DeepSeek (cost-effective alternative)\n# echo \"DEEPSEEK_API_KEY=sk-your-key-here\" >> .env\n\n# Option 3: Claude (Anthropic)\n# echo \"ANTHROPIC_API_KEY=sk-ant-your-key-here\" >> .env\n# Note: Requires: pip install anthropic\n\n# Option 4: Google Gemini\n# echo \"GEMINI_API_KEY=your-key-here\" >> .env\n# Note: Requires: pip install google-generativeai\n\n# Optionally specify which provider to use (defaults to first available)\n# echo \"AI_PROVIDER=openai\" >> .env\n```\n\n**💡 No LLM? No Problem!** PatchPulse works perfectly fine without any AI - you'll still get all the rule-based guardrails and risk scoring. The AI stuff is just extra if you want it.\n\n#### 3. Start PatchPulse\n\n```bash\n# Start all services\ndocker compose up -d\n\n# Check logs\ndocker compose logs -f backend\n\n# Wait for services to be ready (about 10-15 seconds)\n```\n\n#### 4. Access the Application\n\nOnce PatchPulse is running, access it at:\n\n- **Dashboard**: http://localhost:8000/dashboard\n  - Main user interface for monitoring decisions, viewing analytics, and managing configurations\n  - Real-time updates via WebSocket\n  - Risk visualization and decision history\n\n- **API Documentation**: http://localhost:8000/docs\n  - Interactive Swagger/OpenAPI documentation\n  - Test API endpoints directly from the browser\n  - Full API reference\n\n- **Health Check**: http://localhost:8000/health\n  - Service health status\n  - Database connectivity check\n\n- **API Root**: http://localhost:8000/api\n  - API information and available endpoints\n\n#### 5. Start Using PatchPulse\n\n1. **Access the Dashboard**: Open http://localhost:8000/dashboard in your browser\n2. **View Decisions**: See real-time risk analysis and decisions\n3. **Configure Integrations**: Set up GitHub, GitLab, Slack, or other integrations via the API\n4. **Monitor Analytics**: Track risk trends, blocked changes, and system health\n\n**Note**: The dashboard is the main interface for PatchPulse. The website (patchpulse.dev) is a separate marketing site and not part of this repository.\n\n---\n\n## 🔄 How PatchPulse Works\n\n### Deployment Models\n\nPatchPulse can be deployed in two ways:\n\n#### Option 1: Standalone Mode (Recommended for Getting Started)\n\n**Backend runs separately** (Docker Compose, VM, or anywhere):\n- Backend service runs independently\n- Agent runs **outside** your Kubernetes cluster\n- Agent connects to your cluster using `kubeconfig`\n- Best for: Testing, development, or when you don't want to deploy into your cluster\n\n```bash\n# 1. Start backend (runs anywhere)\ndocker compose up -d\n\n# 2. Run agent locally (connects to your cluster via kubeconfig)\ncd app/agent\nexport BACKEND_URL=http://localhost:8000\nexport KUBECONFIG=$HOME/.kube/config  # Points to your cluster\ngo run cmd/agent/main.go\n```\n\n#### Option 2: In-Cluster Mode (Production)\n\n**Both backend and agent run inside Kubernetes**:\n- Backend deployed as a Kubernetes Deployment\n- Agent deployed in the same or different namespace\n- Agent uses in-cluster config (ServiceAccount)\n- Best for: Production deployments, full integration\n\n```bash\n# Deploy both backend and agent to your cluster\nhelm install patchpulse-backend ./helm/backend --namespace patchpulse\nhelm install patchpulse-agent ./helm/agent --namespace patchpulse\n```\n\n### How It Analyzes Your Changes\n\nPatchPulse works in **two ways**:\n\n#### 1. **Git Integration** (Pre-Deployment Analysis)\n- Monitors GitHub/GitLab PRs/MRs\n- Analyzes Kubernetes manifests in diffs\n- Evaluates guardrails **before** code is merged\n- Sends notifications if risky changes detected\n\n```bash\n# Example: PR with risky deployment.yaml\n# PatchPulse detects: \"Missing resource limits\"\n# → Risk score: 50\n# → Decision: Advisory (allows, but warns)\n```\n\n#### 2. **Cluster Monitoring** (Post-Deployment)\n- Agent watches your Kubernetes cluster\n- Collects deployment signals, pod events, node status\n- Detects issues in running workloads\n- Provides real-time cluster health insights\n\n### Complete Workflow\n\n```\n┌─────────────────┐\n│  Developer      │\n│  Creates PR     │\n└────────┬────────┘\n         │\n         ▼\n┌─────────────────┐     ┌──────────────────┐\n│  Git Integration│────▶│  PatchPulse      │\n│  (GitHub/GitLab)│     │  Backend         │\n└─────────────────┘     │  (FastAPI)       │\n                        └────────┬─────────┘\n                                 │\n                        ┌────────▼─────────┐\n                        │  Policy Engine   │\n                        │  + AI Analysis   │\n                        └────────┬─────────┘\n                                 │\n                        ┌────────▼─────────┐\n                        │  Risk Score      │\n                        │  Decision        │\n                        └────────┬─────────┘\n                                 │\n         ┌───────────────────────┼───────────────────────┐\n         │                       │                       │\n         ▼                       ▼                       ▼\n┌─────────────────┐    ┌─────────────────┐   ┌─────────────────┐\n│  Notification   │    │  Dashboard       │   │  Kubernetes     │\n│  (Slack/Email)  │    │  (Web UI)        │   │  Agent          │\n└─────────────────┘    └─────────────────┘   └────────┬────────┘\n                                                       │\n                                                       ▼\n                                              ┌─────────────────┐\n                                              │  Your K8s       │\n                                              │  Cluster        │\n                                              └─────────────────┘\n```\n\n### Connecting to Your Kubernetes Cluster\n\n#### For Standalone Mode:\n\n1. **Ensure you have access to your cluster:**\n```bash\n# Test cluster access\nkubectl get nodes\n\n# If using a remote cluster, make sure kubeconfig is set\nexport KUBECONFIG=$HOME/.kube/config\n```\n\n2. **Start the agent pointing to your cluster:**\n```bash\n# The agent will automatically use your kubeconfig\nexport BACKEND_URL=http://localhost:8000  # Where backend is running\ncd app/agent\ngo run cmd/agent/main.go\n```\n\n#### For In-Cluster Mode:\n\n1. **Deploy PatchPulse to your cluster:**\n```bash\n# Create namespace\nkubectl create namespace patchpulse\n\n# Deploy backend\nhelm install patchpulse-backend ./helm/backend \\\n  --namespace patchpulse \\\n  --set env.DATABASE_URL=\"postgresql://...\"\n\n# Deploy agent (automatically connects to cluster)\nhelm install patchpulse-agent ./helm/agent \\\n  --namespace patchpulse \\\n  --set env.BACKEND_URL=\"http://patchpulse-backend:8000\"\n```\n\n2. **The agent automatically uses in-cluster config** (no kubeconfig needed)\n\n### What Gets Analyzed?\n\n#### From Git (PR/MR Analysis):\n- Kubernetes manifests (Deployments, Services, ConfigMaps, etc.)\n- Changes to resource limits, requests, probes\n- Security context changes\n- Image tag updates\n- Network policy changes\n\n#### From Cluster (Agent Monitoring):\n- Deployment availability and replica counts\n- Pod restart counts\n- Node readiness status\n- Warning events\n- Resource utilization trends\n\n---\n\n## 📖 Table of Contents\n\n- [Architecture](#-architecture)\n- [Configuration](#-configuration)\n- [LLM Provider Setup](#-llm-provider-setup)\n- [API Usage](#-api-usage)\n- [Deployment](#-deployment)\n- [Development](#-development)\n- [Use Cases](#-use-cases)\n- [Contributing](#-contributing)\n- [Support](#-support)\n- [License](#-license)\n\n---\n\n## 🏗️ Architecture\n\n### Components\n\n#### 1. Backend (FastAPI)\n- REST API for change events and decisions\n- Policy engine with 11+ guardrails\n- AI-powered risk analysis (bring your own LLM!)\n- PostgreSQL database for persistence\n- WebSocket support for real-time updates\n\n#### 2. Agent (Go)\n- Kubernetes cluster monitoring\n- Resource snapshotting\n- Event watching\n- Least-privilege RBAC\n\n#### 3. Git Integrations\n- GitHub PR analysis\n- GitLab MR analysis\n- Diff parsing and manifest extraction\n\n#### 4. Notification Integrations\n- Slack notifications with interactive approval buttons\n- Email notifications\n- Microsoft Teams integration\n- PagerDuty integration\n\n#### 5. Dashboard UI (Primary Interface)\n- Real-time decision monitoring via WebSocket\n- Risk visualization and analytics\n- Decision history and filtering\n- Export functionality (CSV/JSON)\n- Accessible at `/dashboard` endpoint\n\n### Data Flow\n\n```\n1. Developer creates PR/MR → Git integration detects change\n2. Change event sent to backend → Policy engine evaluates\n3. AI analysis runs (if configured) → Security scan, recommendations, predictions\n4. Risk score calculated (0-100) → Decision made (allow/block)\n5. Notification sent to Slack/Teams → Decision stored in database\n6. Dashboard updates in real-time via WebSocket\n```\n\n### System Architecture Diagram\n\n```\n┌─────────────┐     ┌──────────────┐     ┌─────────────┐\n│   GitHub    │────▶│ Git Poller   │────▶│  Backend    │\n│   GitLab    │     │              │     │  (FastAPI)  │\n└─────────────┘     └──────────────┘     └──────┬──────┘\n                                                 │\n┌─────────────┐     ┌──────────────┐             │\n│ Kubernetes  │────▶│   Agent     │─────────────┘\n│   Cluster   │     │    (Go)     │\n└─────────────┘     └──────────────┘\n                                                 │\n┌─────────────┐     ┌──────────────┐     ┌─────▼──────┐\n│   Slack     │◀────│ Notifications│◀────│ PostgreSQL │\n│   Teams     │     │              │     │  Database  │\n│  PagerDuty  │     └──────────────┘     └────────────┘\n│   Email     │\n└─────────────┘\n```\n\n---\n\n## 🔧 Configuration\n\n### Environment Variables\n\nCreate a `.env` file in the root directory:\n\n```bash\n# Database\nDATABASE_URL=postgresql://patchpulse:patchpulse@postgres:5432/patchpulse\n\n# Policy Mode (advisory or enforce)\nPOLICY_MODE=advisory\n\n# Logging\nLOG_LEVEL=INFO\n\n# AI Provider - Choose ONE (see LLM Provider Setup section)\nOPENAI_API_KEY=your_openai_api_key\n# OR\n# DEEPSEEK_API_KEY=your_deepseek_api_key\n# OR\n# ANTHROPIC_API_KEY=your_anthropic_api_key\n# OR\n# GEMINI_API_KEY=your_gemini_api_key\n\n# Optional: Specify which provider to use (defaults to first available)\nAI_PROVIDER=openai\n\n# Git Integration\nGITHUB_TOKEN=your_github_token\nGITHUB_REPOS=owner/repo1,owner/repo2\nGITLAB_TOKEN=your_gitlab_token\nGITLAB_PROJECTS=12345,67890\n\n# JWT Secret (auto-generated if not set)\nJWT_SECRET_KEY=your_jwt_secret\n```\n\n### Policy Modes\n\n- **`advisory`**: Logs decisions but doesn't block changes (default)\n  - Best for: Testing, gradual rollout, learning mode\n  - All decisions are logged and visible in dashboard\n  - No changes are blocked\n\n- **`enforce`**: Blocks high-risk changes (score ≥ 70)\n  - Best for: Production environments\n  - High-risk changes are automatically blocked\n  - Requires manual approval for blocked changes\n\n---\n\n## 🤖 LLM Provider Setup\n\nPatchPulse is **100% open source** and supports **bring your own LLM**. You can use any of these providers:\n\n### Supported Providers\n\n| Provider | Cost | Quality | Setup |\n|----------|------|---------|-------|\n| **OpenAI** | $$$ | ⭐⭐⭐⭐⭐ | `OPENAI_API_KEY=sk-...` |\n| **DeepSeek** | $ | ⭐⭐⭐⭐ | `DEEPSEEK_API_KEY=sk-...` |\n| **Claude** | $$$ | ⭐⭐⭐⭐⭐ | `ANTHROPIC_API_KEY=sk-ant-...` |\n| **Gemini** | $$ | ⭐⭐⭐⭐ | `GEMINI_API_KEY=...` |\n\n### OpenAI\n\n```bash\nexport OPENAI_API_KEY=sk-your-key-here\n# Or in .env file:\necho \"OPENAI_API_KEY=sk-your-key-here\" >> .env\n```\n\n**Models**: Uses `gpt-4o-mini` by default (cost-effective). You can modify `ai_analyzer.py` to use other models.\n\n### DeepSeek (Recommended for Cost-Conscious Users)\n\n```bash\nexport DEEPSEEK_API_KEY=sk-your-key-here\n# Or in .env file:\necho \"DEEPSEEK_API_KEY=sk-your-key-here\" >> .env\n```\n\n**Models**: Uses `deepseek-chat` by default. OpenAI-compatible API.\n\n### Claude (Anthropic)\n\n```bash\n# First install the package\npip install anthropic\n\nexport ANTHROPIC_API_KEY=sk-ant-your-key-here\n# Or in .env file:\necho \"ANTHROPIC_API_KEY=sk-ant-your-key-here\" >> .env\n```\n\n**Models**: Uses `claude-3-5-sonnet-20241022` by default.\n\n### Google Gemini\n\n```bash\n# First install the package\npip install google-generativeai\n\nexport GEMINI_API_KEY=your-key-here\n# Or in .env file:\necho \"GEMINI_API_KEY=your-key-here\" >> .env\n```\n\n**Models**: Uses `gemini-1.5-pro` by default.\n\n### Using a Custom OpenAI-Compatible API\n\nPatchPulse supports any OpenAI-compatible API endpoint (Ollama, LocalAI, vLLM, etc.):\n\n```bash\n# Set a dummy API key (not used for local endpoints)\nexport OPENAI_API_KEY=not-used\n\n# Set your custom endpoint\nexport OPENAI_BASE_URL=http://localhost:11434/v1  # Ollama example\n# Or\nexport OPENAI_BASE_URL=http://localhost:8080/v1   # LocalAI example\n\n# Or in .env file:\necho \"OPENAI_API_KEY=not-used\" >> .env\necho \"OPENAI_BASE_URL=http://localhost:11434/v1\" >> .env\n```\n\n**Examples:**\n- **Ollama**: `OPENAI_BASE_URL=http://localhost:11434/v1`\n- **LocalAI**: `OPENAI_BASE_URL=http://localhost:8080/v1`\n- **vLLM**: `OPENAI_BASE_URL=http://localhost:8000/v1`\n- **Any OpenAI-compatible service**: Just set the base URL!\n\nThe system will automatically use your custom endpoint with the OpenAI client.\n\n### No LLM Required\n\n**PatchPulse works perfectly without any LLM!** If no API key is provided:\n- ✅ All rule-based guardrails work\n- ✅ Risk scoring works\n- ✅ All integrations work\n- ✅ Dashboard works\n- ⚠️ AI-powered features are disabled (security scanning, recommendations, predictions)\n\n---\n\n## 📊 API Usage\n\n### Create Change Event\n\n```bash\ncurl -X POST http://localhost:8000/api/v1/change-events \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"source\": \"github\",\n    \"repo\": \"org/repo\",\n    \"sha\": \"abc123\",\n    \"pr_number\": 42,\n    \"branch\": \"feature-branch\",\n    \"files\": [\"k8s/deployment.yaml\"],\n    \"diff_hunks\": [{\n      \"file\": \"k8s/deployment.yaml\",\n      \"hunk\": \"- limits:\\n  cpu: 500m\"\n    }],\n    \"timestamp\": \"2026-01-01T00:00:00Z\"\n  }'\n```\n\n### Get Decisions\n\n```bash\ncurl http://localhost:8000/api/v1/decisions?limit=10\n```\n\n### Get Analytics\n\n```bash\ncurl http://localhost:8000/api/v1/analytics/summary\n```\n\n### Get Decision by ID\n\n```bash\ncurl http://localhost:8000/api/v1/decisions/{decision_id}\n```\n\n### Filter Decisions\n\n```bash\n# Filter by risk score\ncurl \"http://localhost:8000/api/v1/decisions?min_risk=50&max_risk=100\"\n\n# Filter by source\ncurl \"http://localhost:8000/api/v1/decisions?source=github\"\n\n# Filter by date range\ncurl \"http://localhost:8000/api/v1/decisions?start_date=2026-01-01&end_date=2026-01-31\"\n```\n\nSee `/docs` for interactive API documentation.\n\n---\n\n## 🚢 Deployment\n\n### Docker Compose (Recommended for Quick Start)\n\n```bash\ndocker compose up -d\n```\n\n### Kubernetes (Helm)\n\n**Option 1: Using your `.env` file (Recommended)**\n\n```bash\n# Create a values file from your .env\n# This reads your .env file and creates Helm values\ncat > /tmp/patchpulse-values.yaml <<EOF\nenv:\n  DATABASE_URL: \"postgresql://patchpulse:patchpulse@postgres:5432/patchpulse\"\n  POLICY_MODE: \"advisory\"\n  LOG_LEVEL: \"INFO\"\n  OPENAI_API_KEY: \"$(grep OPENAI_API_KEY .env | cut -d '=' -f2)\"\n  DEEPSEEK_API_KEY: \"$(grep DEEPSEEK_API_KEY .env | cut -d '=' -f2 || echo '')\"\n  ANTHROPIC_API_KEY: \"$(grep ANTHROPIC_API_KEY .env | cut -d '=' -f2 || echo '')\"\n  GEMINI_API_KEY: \"$(grep GEMINI_API_KEY .env | cut -d '=' -f2 || echo '')\"\nEOF\n\n# Install backend using values from .env\nhelm install patchpulse-backend ./helm/backend \\\n  --namespace patchpulse \\\n  --create-namespace \\\n  --values /tmp/patchpulse-values.yaml\n\n# Install agent\nhelm install patchpulse-agent ./helm/agent \\\n  --namespace patchpulse \\\n  --set env.BACKEND_URL=http://patchpulse-backend:8000\n```\n\n**Option 2: Using --set-file (Alternative)**\n\n```bash\n# Install backend with API key from .env file\nhelm install patchpulse-backend ./helm/backend \\\n  --namespace patchpulse \\\n  --create-namespace \\\n  --set env.OPENAI_API_KEY=\"$(grep OPENAI_API_KEY .env | cut -d '=' -f2)\" \\\n  --set env.POLICY_MODE=advisory\n\n# Install agent\nhelm install patchpulse-agent ./helm/agent \\\n  --namespace patchpulse \\\n  --set env.BACKEND_URL=http://patchpulse-backend:8000\n```\n\n**Option 3: Manual values override**\n\nEdit `helm/backend/values.yaml` and add your API keys to the `env` section, then install:\n\n```bash\nhelm install patchpulse-backend ./helm/backend \\\n  --namespace patchpulse \\\n  --create-namespace\n```\n\n### Production Considerations\n\n- Use environment variables for secrets (never hardcode)\n- Set up proper TLS/SSL certificates\n- Configure database backups\n- Set up monitoring and alerting\n- Use a managed PostgreSQL database for production\n- Configure rate limiting\n- Set up log aggregation\n- Enable audit logging\n\n---\n\n## 🛠️ Development\n\n### Local Development Setup\n\n```bash\n# Backend\ncd app/backend\npython -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\npip install -r requirements.txt\nuvicorn main:app --reload\n\n# Agent\ncd app/agent\ngo run cmd/agent/main.go\n\n# Git Integration\ncd app/integrations/git\npython poller.py\n```\n\n### Running Tests\n\n```bash\n# Unit tests\ncd app/backend\npytest tests/\n\n# Integration tests\ndocker compose up -d\n./test_api_endpoints.sh\n```\n\n### Project Structure\n\n```\npatchpulse/\n├── app/                    # Application code\n│   ├── backend/           # FastAPI backend service\n│   │   ├── main.py        # Main application entry point\n│   │   ├── models.py      # Pydantic models and SQLAlchemy ORM\n│   │   ├── database.py    # Database connection and setup\n│   │   ├── policy_engine.py # Policy evaluation and guardrails\n│   │   ├── ai_analyzer.py # AI-powered risk analysis (BYO LLM!)\n│   │   ├── ai_features.py # Advanced AI features\n│   │   ├── auth.py        # Authentication system\n│   │   └── requirements.txt\n│   ├── agent/             # Kubernetes agent (Go)\n│   │   ├── cmd/agent/     # Agent main application\n│   │   └── Dockerfile\n│   ├── integrations/     # External integrations\n│   │   ├── git/           # GitHub/GitLab integration\n│   │   ├── slack/         # Slack notifications\n│   │   ├── teams/         # Microsoft Teams integration\n│   │   ├── pagerduty/     # PagerDuty integration\n│   │   └── email/         # Email notifications\n│   └── ui/                # Dashboard UI (served at /dashboard)\n├── docs/                  # Technical documentation\n├── helm/                  # Kubernetes Helm charts\n├── docker-compose.yml     # Local development setup\n└── README.md             # This file\n```\n\n---\n\n## 💼 Use Cases\n\n### 1. CI/CD Pipeline Integration\n\nIntegrate PatchPulse into your CI/CD pipeline to automatically analyze PRs:\n\n```yaml\n# GitHub Actions example\n- name: Analyze with PatchPulse\n  run: |\n    curl -X POST $PATCHPULSE_URL/api/v1/change-events \\\n      -H \"Content-Type: application/json\" \\\n      -d @change-event.json\n```\n\n### 2. Pre-Deployment Validation\n\nValidate Kubernetes manifests before deployment:\n\n```bash\n# Analyze deployment manifests\nkubectl apply --dry-run=client -f deployment.yaml | \\\n  patchpulse analyze --source=manual\n```\n\n### 3. Compliance Auditing\n\nTrack compliance with Kubernetes best practices:\n\n```bash\n# Get compliance report\ncurl http://localhost:8000/api/v1/analytics/compliance\n```\n\n### 4. Incident Prevention\n\nPrevent production incidents by catching risky changes:\n\n- Missing resource limits\n- Security misconfigurations\n- Image tag issues\n- Network policy violations\n\n### 5. Team Education\n\nUse PatchPulse to educate teams on Kubernetes best practices:\n\n- Real-time feedback on PRs\n- Detailed explanations of guardrail violations\n- Historical analytics on common mistakes\n\n---\n\n## 🛡️ Security\n\n- **API keys never exposed** in logs or responses\n- **Least-privilege RBAC** for agent\n- **Encrypted database** connections\n- **TLS** for all API communications\n- **Audit logging** for all decisions\n- **Rate limiting** on API endpoints\n- **Self-hosted** - your data stays on your infrastructure\n\nSee [SECURITY.md](SECURITY.md) for detailed security information.\n\n---\n\n## 🤝 Contributing\n\nContributions are welcome! This is a solo project, so any help is genuinely appreciated.\n\n1. Fork the repo\n2. Create a branch (`git checkout -b feature/your-feature`)\n3. Make your changes\n4. Commit (`git commit -m 'Add your feature'`)\n5. Push (`git push origin feature/your-feature`)\n6. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for more details.\n\n**What I'd love help with:**\n- 🐛 Bug fixes (especially edge cases I haven't hit yet)\n- ✨ New features (if you have ideas, open an issue first to discuss)\n- 📚 Documentation (I'm not great at writing docs, so improvements are welcome)\n- 🧪 Tests (more test coverage is always good)\n- 🎨 UI improvements (the dashboard could definitely be prettier)\n- 🔌 New integrations (want to add something? Let's talk)\n\n---\n\n## 📄 License\n\nThis project is licensed under the **PatchPulse Non-Commercial License** - see the [LICENSE](LICENSE) file for details.\n\n**✅ Permitted Uses:**\n- Personal use\n- Educational use\n- Research and development\n- Internal use within non-profit organizations\n- Contributing to the PatchPulse project\n- Forking and modifying for personal/educational purposes\n\n**❌ Prohibited Uses:**\n- Commercial use (selling, licensing, or providing as a service)\n- Use in commercial products or services\n- Reselling or redistributing for profit\n- Use by for-profit companies without explicit written permission\n\n**💼 Commercial Licensing:**\nFor commercial use, please contact us to obtain a commercial license. Commercial licenses are available for:\n- SaaS providers\n- Enterprise deployments\n- Commercial products incorporating PatchPulse\n- Consulting services using PatchPulse\n\n**Contact:** amarkdotdev@gmail.com\n\nThis license protects the open-source nature of PatchPulse while ensuring commercial use requires proper licensing.\n\n---\n\n## 🆘 Need Help?\n\n**Documentation**: http://localhost:8000/docs (when running locally)  \n**Website**: https://patchpulse.dev  \n**Issues**: https://github.com/amarkdotdev/patchpulse/issues  \n**Email**: amarkdotdev@gmail.com\n\n**Ways to help:**\n- ⭐ Star the repo if you find it useful (helps others discover it)\n- 🐛 Found a bug? Open an issue - I'll try to fix it\n- 💡 Have an idea? Open a discussion or issue\n- 📖 Docs unclear? Send a PR to improve them\n\n---\n\n## ☕ Support the Project\n\nIf PatchPulse has saved you from a late-night incident or just made your life easier, consider buying me a coffee:\n\n**[☕ Buy Me a Coffee](https://buymeacoffee.com/aaronmark)**\n\nIt's not required at all, but it's a nice way to say thanks and helps me justify spending more time on this project. Every bit helps! 🙏\n\n---\n\n## 🎯 Roadmap\n\n- [ ] Multi-tenant support (in progress)\n- [ ] Custom guardrail DSL\n- [ ] Integration with more Git providers (Bitbucket, Azure DevOps)\n- [ ] Additional AI provider support\n- [ ] Compliance reporting (SOC2, ISO27001)\n- [ ] Enhanced documentation\n- [ ] Local LLM support (Ollama, LocalAI)\n- [ ] Webhook support for real-time PR analysis\n- [ ] Custom risk scoring algorithms\n- [ ] Policy templates library\n\n---\n\n## 👨‍💻 Hey, I'm Aaron\n\nI'm a DevOps engineer based in Israel 🇮🇱, and I built PatchPulse because I was tired of preventable production incidents. \n\nYou know those moments when you're debugging at 2am and think \"we should've caught this earlier\"? That's what PatchPulse is for. It's the tool I wish I had when I was managing Kubernetes clusters at scale.\n\nI built this in my spare time, iterating based on real problems I've faced. It's not perfect, but it's useful, and I'm sharing it because I think other teams might find it helpful too.\n\n**Want to chat?**\n- 📧 Email: amarkdotdev@gmail.com\n- 🐙 GitHub: [@amarkdotdev](https://github.com/amarkdotdev)\n- ☕ Buy Me a Coffee: [buymeacoffee.com/aaronmark](https://buymeacoffee.com/aaronmark) (if PatchPulse saves you from a late-night incident, consider it 😊)\n\n---\n\n## 🙏 Thanks\n\nThis project wouldn't exist without the open source community. Special shoutout to everyone who's contributed, reported bugs, or just used PatchPulse and gave feedback.\n\nBuilt with:\n- **FastAPI** - Because Python web frameworks don't have to be slow\n- **PostgreSQL** - Reliable and battle-tested\n- **Go** - For the Kubernetes agent (because sometimes you need speed)\n- **Docker** - Makes deployment actually bearable\n- **Kubernetes** - The thing we're all trying to make safer\n\n---\n\n<div align=\"center\">\n\n**🔓 Open Source | 🤖 Bring Your Own LLM | 🚀 Self-Hosted**\n\n**Made with ❤️ in Israel for the Kubernetes community worldwide**\n\n[⭐ Star on GitHub](https://github.com/amarkdotdev/patchpulse) • [📖 Documentation](https://patchpulse.dev) • [☕ Buy Me a Coffee](https://buymeacoffee.com/aaronmark) • [🐛 Report Bug](https://github.com/amarkdotdev/patchpulse/issues)\n\n</div>\n"}, "5ed5c7f15220e7725f5b96d5530b77481d889ea8": {"t": 1785764231.0358832, "n": 28395, "h": "0ae794ffef1e00cd", "c": "# PatchPulse\n\n<div align=\"center\">\n\n**🔓 100% Open Source | 🤖 Bring Your Own LLM | 🚀 Self-Hosted Kubernetes Risk Analysis**\n\n[![License](https://img.shields.io/badge/license-Non--Commercial-blue.svg)](LICENSE)\n[![GitHub stars](https://img.shields.io/github/stars/amarkdotdev/patchpulse?style=social)](https://github.com/amarkdotdev/patchpulse)\n[![Website](https://img.shields.io/badge/website-patchpulse.dev-blue)](https://patchpulse.dev)\n[![Buy Me a Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-☕-yellow)](https://buymeacoffee.com/aaronmark)\n\n**Prevent production incidents before they happen**\n\n[Quick Start](#-quick-start) • [Documentation](#-documentation) • [Features](#-key-features) • [Support](#-support)\n\n</div>\n\n---\n\n## 🎯 What is PatchPulse?\n\nAfter one too many 3am pages from production incidents that could've been caught earlier, I built PatchPulse. It's a self-hosted tool that analyzes your Kubernetes changes before they hit production, combining rule-based guardrails with optional AI analysis to give you explainable risk scores.\n\nThink of it as a safety net for your deployments - it catches the stuff that slips through code review and CI/CD checks.\n\n### Why I Built This\n\nI've been there - you merge a PR, deploy to production, and suddenly pods are OOMKilled because someone forgot resource limits. Or worse, a security misconfiguration opens up your cluster. PatchPulse catches these issues before they become incidents.\n\n- **🛡️ Catch Problems Early**: See risky changes before they reach production\n- **🔍 Understand Why**: Get clear explanations when something's flagged\n- **🤖 Optional AI**: Use AI for deeper analysis, or skip it entirely - your call\n- **⚡ Real-Time Alerts**: Know immediately when something's wrong\n- **🔓 100% Open Source**: No vendor lock-in, no SaaS fees, just code you can trust\n- **🏠 Your Data, Your Control**: Everything runs on your infrastructure\n\n---\n\n## ✨ Key Features\n\n### Core Capabilities\n\n- **🔓 Fully Open Source** - Non-commercial license, no vendor lock-in\n- **🤖 Bring Your Own LLM** - Use OpenAI, DeepSeek, Claude, Gemini, or any OpenAI-compatible API\n- **🏠 Self-Hosted** - Your data stays on your infrastructure\n- **🛡️ 11+ Guardrails** - Rule-based checks for Kubernetes best practices\n- **🧠 AI-Powered Analysis** - Security scanning, recommendations, incident prediction\n- **⚡ Real-Time** - WebSocket updates and instant notifications\n- **🔌 Integrations** - GitHub, GitLab, Slack, Teams, PagerDuty, Email\n- **📊 Enterprise Features** - Admission webhooks, policy bundles, SBOM verification, multi-tenancy\n\n### Guardrails Included\n\n1. **Resource Limits** - Ensures CPU/memory limits are set\n2. **Resource Requests** - Validates resource requests are configured\n3. **Readiness Probes** - Checks for readiness probe configuration\n4. **Liveness Probes** - Validates liveness probe setup\n5. **Security Context** - Enforces security context settings\n6. **Image Tags** - Prevents `latest` tag usage\n7. **Namespace Validation** - Ensures proper namespace usage\n8. **Service Account** - Validates service account configuration\n9. **Network Policies** - Checks network policy compliance\n10. **Resource Quotas** - Validates resource quota adherence\n11. **Pod Disruption Budgets** - Ensures PDB configuration\n\n---\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- **Docker** (running) - Required for containerized deployment\n- **Python 3.11+** - For local development\n- **Go 1.21+** - For agent development (optional)\n- **kubectl** - For Kubernetes integration (optional)\n\n### Installation Steps\n\n#### 1. Clone the Repository\n\n```bash\ngit clone https://github.com/amarkdotdev/patchpulse.git\ncd patchpulse\n```\n\n#### 2. Configure Your LLM Provider (Optional)\n\nPatchPulse supports multiple AI providers. **You only need to provide an API key for ONE provider:**\n\n```bash\n# Create .env file\ntouch .env\n\n# Option 1: OpenAI (recommended for best results)\necho \"OPENAI_API_KEY=sk-your-key-here\" >> .env\n\n# Option 2: DeepSeek (cost-effective alternative)\n# echo \"DEEPSEEK_API_KEY=sk-your-key-here\" >> .env\n\n# Option 3: Claude (Anthropic)\n# echo \"ANTHROPIC_API_KEY=sk-ant-your-key-here\" >> .env\n# Note: Requires: pip install anthropic\n\n# Option 4: Google Gemini\n# echo \"GEMINI_API_KEY=your-key-here\" >> .env\n# Note: Requires: pip install google-generativeai\n\n# Optionally specify which provider to use (defaults to first available)\n# echo \"AI_PROVIDER=openai\" >> .env\n```\n\n**💡 No LLM? No Problem!** PatchPulse works perfectly fine without any AI - you'll still get all the rule-based guardrails and risk scoring. The AI stuff is just extra if you want it.\n\n#### 3. Start PatchPulse\n\n```bash\n# Start all services\ndocker compose up -d\n\n# Check logs\ndocker compose logs -f backend\n\n# Wait for services to be ready (about 10-15 seconds)\n```\n\n#### 4. Access the Application\n\nOnce PatchPulse is running, access it at:\n\n- **Dashboard**: http://localhost:8000/dashboard\n  - Main user interface for monitoring decisions, viewing analytics, and managing configurations\n  - Real-time updates via WebSocket\n  - Risk visualization and decision history\n\n- **API Documentation**: http://localhost:8000/docs\n  - Interactive Swagger/OpenAPI documentation\n  - Test API endpoints directly from the browser\n  - Full API reference\n\n- **Health Check**: http://localhost:8000/health\n  - Service health status\n  - Database connectivity check\n\n- **API Root**: http://localhost:8000/api\n  - API information and available endpoints\n\n#### 5. Start Using PatchPulse\n\n1. **Access the Dashboard**: Open http://localhost:8000/dashboard in your browser\n2. **View Decisions**: See real-time risk analysis and decisions\n3. **Configure Integrations**: Set up GitHub, GitLab, Slack, or other integrations via the API\n4. **Monitor Analytics**: Track risk trends, blocked changes, and system health\n\n**Note**: The dashboard is the main interface for PatchPulse. The website (patchpulse.dev) is a separate marketing site and not part of this repository.\n\n---\n\n## 🔄 How PatchPulse Works\n\n### Deployment Models\n\nPatchPulse can be deployed in two ways:\n\n#### Option 1: Standalone Mode (Recommended for Getting Started)\n\n**Backend runs separately** (Docker Compose, VM, or anywhere):\n- Backend service runs independently\n- Agent runs **outside** your Kubernetes cluster\n- Agent connects to your cluster using `kubeconfig`\n- Best for: Testing, development, or when you don't want to deploy into your cluster\n\n```bash\n# 1. Start backend (runs anywhere)\ndocker compose up -d\n\n# 2. Run agent locally (connects to your cluster via kubeconfig)\ncd app/agent\nexport BACKEND_URL=http://localhost:8000\nexport KUBECONFIG=$HOME/.kube/config  # Points to your cluster\ngo run cmd/agent/main.go\n```\n\n#### Option 2: In-Cluster Mode (Production)\n\n**Both backend and agent run inside Kubernetes**:\n- Backend deployed as a Kubernetes Deployment\n- Agent deployed in the same or different namespace\n- Agent uses in-cluster config (ServiceAccount)\n- Best for: Production deployments, full integration\n\n```bash\n# Deploy both backend and agent to your cluster\nhelm install patchpulse-backend ./helm/backend --namespace patchpulse\nhelm install patchpulse-agent ./helm/agent --namespace patchpulse\n```\n\n### How It Analyzes Your Changes\n\nPatchPulse works in **two ways**:\n\n#### 1. **Git Integration** (Pre-Deployment Analysis)\n- Monitors GitHub/GitLab PRs/MRs\n- Analyzes Kubernetes manifests in diffs\n- Evaluates guardrails **before** code is merged\n- Sends notifications if risky changes detected\n\n```bash\n# Example: PR with risky deployment.yaml\n# PatchPulse detects: \"Missing resource limits\"\n# → Risk score: 50\n# → Decision: Advisory (allows, but warns)\n```\n\n#### 2. **Cluster Monitoring** (Post-Deployment)\n- Agent watches your Kubernetes cluster\n- Collects deployment signals, pod events, node status\n- Detects issues in running workloads\n- Provides real-time cluster health insights\n\n### Complete Workflow\n\n```\n┌─────────────────┐\n│  Developer      │\n│  Creates PR     │\n└────────┬────────┘\n         │\n         ▼\n┌─────────────────┐     ┌──────────────────┐\n│  Git Integration│────▶│  PatchPulse      │\n│  (GitHub/GitLab)│     │  Backend         │\n└─────────────────┘     │  (FastAPI)       │\n                        └────────┬─────────┘\n                                 │\n                        ┌────────▼─────────┐\n                        │  Policy Engine   │\n                        │  + AI Analysis   │\n                        └────────┬─────────┘\n                                 │\n                        ┌────────▼─────────┐\n                        │  Risk Score      │\n                        │  Decision        │\n                        └────────┬─────────┘\n                                 │\n         ┌───────────────────────┼───────────────────────┐\n         │                       │                       │\n         ▼                       ▼                       ▼\n┌─────────────────┐    ┌─────────────────┐   ┌─────────────────┐\n│  Notification   │    │  Dashboard       │   │  Kubernetes     │\n│  (Slack/Email)  │    │  (Web UI)        │   │  Agent          │\n└─────────────────┘    └─────────────────┘   └────────┬────────┘\n                                                       │\n                                                       ▼\n                                              ┌─────────────────┐\n                                              │  Your K8s       │\n                                              │  Cluster        │\n                                              └─────────────────┘\n```\n\n### Connecting to Your Kubernetes Cluster\n\n#### For Standalone Mode:\n\n1. **Ensure you have access to your cluster:**\n```bash\n# Test cluster access\nkubectl get nodes\n\n# If using a remote cluster, make sure kubeconfig is set\nexport KUBECONFIG=$HOME/.kube/config\n```\n\n2. **Start the agent pointing to your cluster:**\n```bash\n# The agent will automatically use your kubeconfig\nexport BACKEND_URL=http://localhost:8000  # Where backend is running\ncd app/agent\ngo run cmd/agent/main.go\n```\n\n#### For In-Cluster Mode:\n\n1. **Deploy PatchPulse to your cluster:**\n```bash\n# Create namespace\nkubectl create namespace patchpulse\n\n# Deploy backend\nhelm install patchpulse-backend ./helm/backend \\\n  --namespace patchpulse \\\n  --set env.DATABASE_URL=\"postgresql://...\"\n\n# Deploy agent (automatically connects to cluster)\nhelm install patchpulse-agent ./helm/agent \\\n  --namespace patchpulse \\\n  --set env.BACKEND_URL=\"http://patchpulse-backend:8000\"\n```\n\n2. **The agent automatically uses in-cluster config** (no kubeconfig needed)\n\n### What Gets Analyzed?\n\n#### From Git (PR/MR Analysis):\n- Kubernetes manifests (Deployments, Services, ConfigMaps, etc.)\n- Changes to resource limits, requests, probes\n- Security context changes\n- Image tag updates\n- Network policy changes\n\n#### From Cluster (Agent Monitoring):\n- Deployment availability and replica counts\n- Pod restart counts\n- Node readiness status\n- Warning events\n- Resource utilization trends\n\n---\n\n## 📖 Table of Contents\n\n- [Architecture](#-architecture)\n- [Configuration](#-configuration)\n- [LLM Provider Setup](#-llm-provider-setup)\n- [API Usage](#-api-usage)\n- [Deployment](#-deployment)\n- [Development](#-development)\n- [Use Cases](#-use-cases)\n- [Contributing](#-contributing)\n- [Support](#-support)\n- [License](#-license)\n\n---\n\n## 🏗️ Architecture\n\n### Components\n\n#### 1. Backend (FastAPI)\n- REST API for change events and decisions\n- Policy engine with 11+ guardrails\n- AI-powered risk analysis (bring your own LLM!)\n- PostgreSQL database for persistence\n- WebSocket support for real-time updates\n\n#### 2. Agent (Go)\n- Kubernetes cluster monitoring\n- Resource snapshotting\n- Event watching\n- Least-privilege RBAC\n\n#### 3. Git Integrations\n- GitHub PR analysis\n- GitLab MR analysis\n- Diff parsing and manifest extraction\n\n#### 4. Notification Integrations\n- Slack notifications with interactive approval buttons\n- Email notifications\n- Microsoft Teams integration\n- PagerDuty integration\n\n#### 5. Dashboard UI (Primary Interface)\n- Real-time decision monitoring via WebSocket\n- Risk visualization and analytics\n- Decision history and filtering\n- Export functionality (CSV/JSON)\n- Accessible at `/dashboard` endpoint\n\n### Data Flow\n\n```\n1. Developer creates PR/MR → Git integration detects change\n2. Change event sent to backend → Policy engine evaluates\n3. AI analysis runs (if configured) → Security scan, recommendations, predictions\n4. Risk score calculated (0-100) → Decision made (allow/block)\n5. Notification sent to Slack/Teams → Decision stored in database\n6. Dashboard updates in real-time via WebSocket\n```\n\n### System Architecture Diagram\n\n```\n┌─────────────┐     ┌──────────────┐     ┌─────────────┐\n│   GitHub    │────▶│ Git Poller   │────▶│  Backend    │\n│   GitLab    │     │              │     │  (FastAPI)  │\n└─────────────┘     └──────────────┘     └──────┬──────┘\n                                                 │\n┌─────────────┐     ┌──────────────┐             │\n│ Kubernetes  │────▶│   Agent     │─────────────┘\n│   Cluster   │     │    (Go)     │\n└─────────────┘     └──────────────┘\n                                                 │\n┌─────────────┐     ┌──────────────┐     ┌─────▼──────┐\n│   Slack     │◀────│ Notifications│◀────│ PostgreSQL │\n│   Teams     │     │              │     │  Database  │\n│  PagerDuty  │     └──────────────┘     └────────────┘\n│   Email     │\n└─────────────┘\n```\n\n---\n\n## 🔧 Configuration\n\n### Environment Variables\n\nCreate a `.env` file in the root directory:\n\n```bash\n# Database\nDATABASE_URL=postgresql://patchpulse:patchpulse@postgres:5432/patchpulse\n\n# Policy Mode (advisory or enforce)\nPOLICY_MODE=advisory\n\n# Logging\nLOG_LEVEL=INFO\n\n# AI Provider - Choose ONE (see LLM Provider Setup section)\nOPENAI_API_KEY=your_openai_api_key\n# OR\n# DEEPSEEK_API_KEY=your_deepseek_api_key\n# OR\n# ANTHROPIC_API_KEY=your_anthropic_api_key\n# OR\n# GEMINI_API_KEY=your_gemini_api_key\n\n# Optional: Specify which provider to use (defaults to first available)\nAI_PROVIDER=openai\n\n# Git Integration\nGITHUB_TOKEN=your_github_token\nGITHUB_REPOS=owner/repo1,owner/repo2\nGITLAB_TOKEN=your_gitlab_token\nGITLAB_PROJECTS=12345,67890\n\n# JWT Secret (auto-generated if not set)\nJWT_SECRET_KEY=your_jwt_secret\n```\n\n### Policy Modes\n\n- **`advisory`**: Logs decisions but doesn't block changes (default)\n  - Best for: Testing, gradual rollout, learning mode\n  - All decisions are logged and visible in dashboard\n  - No changes are blocked\n\n- **`enforce`**: Blocks high-risk changes (score ≥ 70)\n  - Best for: Production environments\n  - High-risk changes are automatically blocked\n  - Requires manual approval for blocked changes\n\n---\n\n## 🤖 LLM Provider Setup\n\nPatchPulse is **100% open source** and supports **bring your own LLM**. You can use any of these providers:\n\n### Supported Providers\n\n| Provider | Cost | Quality | Setup |\n|----------|------|---------|-------|\n| **OpenAI** | $$$ | ⭐⭐⭐⭐⭐ | `OPENAI_API_KEY=sk-...` |\n| **DeepSeek** | $ | ⭐⭐⭐⭐ | `DEEPSEEK_API_KEY=sk-...` |\n| **Claude** | $$$ | ⭐⭐⭐⭐⭐ | `ANTHROPIC_API_KEY=sk-ant-...` |\n| **Gemini** | $$ | ⭐⭐⭐⭐ | `GEMINI_API_KEY=...` |\n\n### OpenAI\n\n```bash\nexport OPENAI_API_KEY=sk-your-key-here\n# Or in .env file:\necho \"OPENAI_API_KEY=sk-your-key-here\" >> .env\n```\n\n**Models**: Uses `gpt-4o-mini` by default (cost-effective). You can modify `ai_analyzer.py` to use other models.\n\n### DeepSeek (Recommended for Cost-Conscious Users)\n\n```bash\nexport DEEPSEEK_API_KEY=sk-your-key-here\n# Or in .env file:\necho \"DEEPSEEK_API_KEY=sk-your-key-here\" >> .env\n```\n\n**Models**: Uses `deepseek-chat` by default. OpenAI-compatible API.\n\n### Claude (Anthropic)\n\n```bash\n# First install the package\npip install anthropic\n\nexport ANTHROPIC_API_KEY=sk-ant-your-key-here\n# Or in .env file:\necho \"ANTHROPIC_API_KEY=sk-ant-your-key-here\" >> .env\n```\n\n**Models**: Uses `claude-3-5-sonnet-20241022` by default.\n\n### Google Gemini\n\n```bash\n# First install the package\npip install google-generativeai\n\nexport GEMINI_API_KEY=your-key-here\n# Or in .env file:\necho \"GEMINI_API_KEY=your-key-here\" >> .env\n```\n\n**Models**: Uses `gemini-1.5-pro` by default.\n\n### Using a Custom OpenAI-Compatible API\n\nPatchPulse supports any OpenAI-compatible API endpoint (Ollama, LocalAI, vLLM, etc.):\n\n```bash\n# Set a dummy API key (not used for local endpoints)\nexport OPENAI_API_KEY=not-used\n\n# Set your custom endpoint\nexport OPENAI_BASE_URL=http://localhost:11434/v1  # Ollama example\n# Or\nexport OPENAI_BASE_URL=http://localhost:8080/v1   # LocalAI example\n\n# Or in .env file:\necho \"OPENAI_API_KEY=not-used\" >> .env\necho \"OPENAI_BASE_URL=http://localhost:11434/v1\" >> .env\n```\n\n**Examples:**\n- **Ollama**: `OPENAI_BASE_URL=http://localhost:11434/v1`\n- **LocalAI**: `OPENAI_BASE_URL=http://localhost:8080/v1`\n- **vLLM**: `OPENAI_BASE_URL=http://localhost:8000/v1`\n- **Any OpenAI-compatible service**: Just set the base URL!\n\nThe system will automatically use your custom endpoint with the OpenAI client.\n\n### No LLM Required\n\n**PatchPulse works perfectly without any LLM!** If no API key is provided:\n- ✅ All rule-based guardrails work\n- ✅ Risk scoring works\n- ✅ All integrations work\n- ✅ Dashboard works\n- ⚠️ AI-powered features are disabled (security scanning, recommendations, predictions)\n\n---\n\n## 📊 API Usage\n\n### Create Change Event\n\n```bash\ncurl -X POST http://localhost:8000/api/v1/change-events \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"source\": \"github\",\n    \"repo\": \"org/repo\",\n    \"sha\": \"abc123\",\n    \"pr_number\": 42,\n    \"branch\": \"feature-branch\",\n    \"files\": [\"k8s/deployment.yaml\"],\n    \"diff_hunks\": [{\n      \"file\": \"k8s/deployment.yaml\",\n      \"hunk\": \"- limits:\\n  cpu: 500m\"\n    }],\n    \"timestamp\": \"2026-01-01T00:00:00Z\"\n  }'\n```\n\n### Get Decisions\n\n```bash\ncurl http://localhost:8000/api/v1/decisions?limit=10\n```\n\n### Get Analytics\n\n```bash\ncurl http://localhost:8000/api/v1/analytics/summary\n```\n\n### Get Decision by ID\n\n```bash\ncurl http://localhost:8000/api/v1/decisions/{decision_id}\n```\n\n### Filter Decisions\n\n```bash\n# Filter by risk score\ncurl \"http://localhost:8000/api/v1/decisions?min_risk=50&max_risk=100\"\n\n# Filter by source\ncurl \"http://localhost:8000/api/v1/decisions?source=github\"\n\n# Filter by date range\ncurl \"http://localhost:8000/api/v1/decisions?start_date=2026-01-01&end_date=2026-01-31\"\n```\n\nSee `/docs` for interactive API documentation.\n\n---\n\n## 🚢 Deployment\n\n### Docker Compose (Recommended for Quick Start)\n\n```bash\ndocker compose up -d\n```\n\n### Kubernetes (Helm)\n\n**Option 1: Using your `.env` file (Recommended)**\n\n```bash\n# Create a values file from your .env\n# This reads your .env file and creates Helm values\ncat > /tmp/patchpulse-values.yaml <<EOF\nenv:\n  DATABASE_URL: \"postgresql://patchpulse:patchpulse@postgres:5432/patchpulse\"\n  POLICY_MODE: \"advisory\"\n  LOG_LEVEL: \"INFO\"\n  OPENAI_API_KEY: \"$(grep OPENAI_API_KEY .env | cut -d '=' -f2)\"\n  DEEPSEEK_API_KEY: \"$(grep DEEPSEEK_API_KEY .env | cut -d '=' -f2 || echo '')\"\n  ANTHROPIC_API_KEY: \"$(grep ANTHROPIC_API_KEY .env | cut -d '=' -f2 || echo '')\"\n  GEMINI_API_KEY: \"$(grep GEMINI_API_KEY .env | cut -d '=' -f2 || echo '')\"\nEOF\n\n# Install backend using values from .env\nhelm install patchpulse-backend ./helm/backend \\\n  --namespace patchpulse \\\n  --create-namespace \\\n  --values /tmp/patchpulse-values.yaml\n\n# Install agent\nhelm install patchpulse-agent ./helm/agent \\\n  --namespace patchpulse \\\n  --set env.BACKEND_URL=http://patchpulse-backend:8000\n```\n\n**Option 2: Using --set-file (Alternative)**\n\n```bash\n# Install backend with API key from .env file\nhelm install patchpulse-backend ./helm/backend \\\n  --namespace patchpulse \\\n  --create-namespace \\\n  --set env.OPENAI_API_KEY=\"$(grep OPENAI_API_KEY .env | cut -d '=' -f2)\" \\\n  --set env.POLICY_MODE=advisory\n\n# Install agent\nhelm install patchpulse-agent ./helm/agent \\\n  --namespace patchpulse \\\n  --set env.BACKEND_URL=http://patchpulse-backend:8000\n```\n\n**Option 3: Manual values override**\n\nEdit `helm/backend/values.yaml` and add your API keys to the `env` section, then install:\n\n```bash\nhelm install patchpulse-backend ./helm/backend \\\n  --namespace patchpulse \\\n  --create-namespace\n```\n\n### Production Considerations\n\n- Use environment variables for secrets (never hardcode)\n- Set up proper TLS/SSL certificates\n- Configure database backups\n- Set up monitoring and alerting\n- Use a managed PostgreSQL database for production\n- Configure rate limiting\n- Set up log aggregation\n- Enable audit logging\n\n---\n\n## 🛠️ Development\n\n### Local Development Setup\n\n```bash\n# Backend\ncd app/backend\npython -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\npip install -r requirements.txt\nuvicorn main:app --reload\n\n# Agent\ncd app/agent\ngo run cmd/agent/main.go\n\n# Git Integration\ncd app/integrations/git\npython poller.py\n```\n\n### Running Tests\n\n```bash\n# Unit tests\ncd app/backend\npytest tests/\n\n# Integration tests\ndocker compose up -d\n./test_api_endpoints.sh\n```\n\n### Project Structure\n\n```\npatchpulse/\n├── app/                    # Application code\n│   ├── backend/           # FastAPI backend service\n│   │   ├── main.py        # Main application entry point\n│   │   ├── models.py      # Pydantic models and SQLAlchemy ORM\n│   │   ├── database.py    # Database connection and setup\n│   │   ├── policy_engine.py # Policy evaluation and guardrails\n│   │   ├── ai_analyzer.py # AI-powered risk analysis (BYO LLM!)\n│   │   ├── ai_features.py # Advanced AI features\n│   │   ├── auth.py        # Authentication system\n│   │   └── requirements.txt\n│   ├── agent/             # Kubernetes agent (Go)\n│   │   ├── cmd/agent/     # Agent main application\n│   │   └── Dockerfile\n│   ├── integrations/     # External integrations\n│   │   ├── git/           # GitHub/GitLab integration\n│   │   ├── slack/         # Slack notifications\n│   │   ├── teams/         # Microsoft Teams integration\n│   │   ├── pagerduty/     # PagerDuty integration\n│   │   └── email/         # Email notifications\n│   └── ui/                # Dashboard UI (served at /dashboard)\n├── docs/                  # Technical documentation\n├── helm/                  # Kubernetes Helm charts\n├── docker-compose.yml     # Local development setup\n└── README.md             # This file\n```\n\n---\n\n## 💼 Use Cases\n\n### 1. CI/CD Pipeline Integration\n\nIntegrate PatchPulse into your CI/CD pipeline to automatically analyze PRs:\n\n```yaml\n# GitHub Actions example\n- name: Analyze with PatchPulse\n  run: |\n    curl -X POST $PATCHPULSE_URL/api/v1/change-events \\\n      -H \"Content-Type: application/json\" \\\n      -d @change-event.json\n```\n\n### 2. Pre-Deployment Validation\n\nValidate Kubernetes manifests before deployment:\n\n```bash\n# Analyze deployment manifests\nkubectl apply --dry-run=client -f deployment.yaml | \\\n  patchpulse analyze --source=manual\n```\n\n### 3. Compliance Auditing\n\nTrack compliance with Kubernetes best practices:\n\n```bash\n# Get compliance report\ncurl http://localhost:8000/api/v1/analytics/compliance\n```\n\n### 4. Incident Prevention\n\nPrevent production incidents by catching risky changes:\n\n- Missing resource limits\n- Security misconfigurations\n- Image tag issues\n- Network policy violations\n\n### 5. Team Education\n\nUse PatchPulse to educate teams on Kubernetes best practices:\n\n- Real-time feedback on PRs\n- Detailed explanations of guardrail violations\n- Historical analytics on common mistakes\n\n---\n\n## 🛡️ Security\n\n- **API keys never exposed** in logs or responses\n- **Least-privilege RBAC** for agent\n- **Encrypted database** connections\n- **TLS** for all API communications\n- **Audit logging** for all decisions\n- **Rate limiting** on API endpoints\n- **Self-hosted** - your data stays on your infrastructure\n\nSee [SECURITY.md](SECURITY.md) for detailed security information.\n\n---\n\n## 🤝 Contributing\n\nContributions are welcome! This is a solo project, so any help is genuinely appreciated.\n\n1. Fork the repo\n2. Create a branch (`git checkout -b feature/your-feature`)\n3. Make your changes\n4. Commit (`git commit -m 'Add your feature'`)\n5. Push (`git push origin feature/your-feature`)\n6. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for more details.\n\n**What I'd love help with:**\n- 🐛 Bug fixes (especially edge cases I haven't hit yet)\n- ✨ New features (if you have ideas, open an issue first to discuss)\n- 📚 Documentation (I'm not great at writing docs, so improvements are welcome)\n- 🧪 Tests (more test coverage is always good)\n- 🎨 UI improvements (the dashboard could definitely be prettier)\n- 🔌 New integrations (want to add something? Let's talk)\n\n---\n\n## 📄 License\n\nThis project is licensed under the **PatchPulse Non-Commercial License** - see the [LICENSE](LICENSE) file for details.\n\n**✅ Permitted Uses:**\n- Personal use\n- Educational use\n- Research and development\n- Internal use within non-profit organizations\n- Contributing to the PatchPulse project\n- Forking and modifying for personal/educational purposes\n\n**❌ Prohibited Uses:**\n- Commercial use (selling, licensing, or providing as a service)\n- Use in commercial products or services\n- Reselling or redistributing for profit\n- Use by for-profit companies without explicit written permission\n\n**💼 Commercial Licensing:**\nFor commercial use, please contact us to obtain a commercial license. Commercial licenses are available for:\n- SaaS providers\n- Enterprise deployments\n- Commercial products incorporating PatchPulse\n- Consulting services using PatchPulse\n\n**Contact:** amarkdotdev@gmail.com\n\nThis license protects the open-source nature of PatchPulse while ensuring commercial use requires proper licensing.\n\n---\n\n## 🆘 Need Help?\n\n**Documentation**: http://localhost:8000/docs (when running locally)  \n**Website**: https://patchpulse.dev  \n**Issues**: https://github.com/amarkdotdev/patchpulse/issues  \n**Email**: amarkdotdev@gmail.com\n\n**Ways to help:**\n- ⭐ Star the repo if you find it useful (helps others discover it)\n- 🐛 Found a bug? Open an issue - I'll try to fix it\n- 💡 Have an idea? Open a discussion or issue\n- 📖 Docs unclear? Send a PR to improve them\n\n---\n\n## ☕ Support the Project\n\nIf PatchPulse has saved you from a late-night incident or just made your life easier, consider buying me a coffee:\n\n**[☕ Buy Me a Coffee](https://buymeacoffee.com/aaronmark)**\n\nIt's not required at all, but it's a nice way to say thanks and helps me justify spending more time on this project. Every bit helps! 🙏\n\n---\n\n## 🎯 Roadmap\n\n- [ ] Multi-tenant support (in progress)\n- [ ] Custom guardrail DSL\n- [ ] Integration with more Git providers (Bitbucket, Azure DevOps)\n- [ ] Additional AI provider support\n- [ ] Compliance reporting (SOC2, ISO27001)\n- [ ] Enhanced documentation\n- [ ] Local LLM support (Ollama, LocalAI)\n- [ ] Webhook support for real-time PR analysis\n- [ ] Custom risk scoring algorithms\n- [ ] Policy templates library\n\n---\n\n## 👨‍💻 Hey, I'm Aaron\n\nI'm a DevOps engineer based in Israel 🇮🇱, and I built PatchPulse because I was tired of preventable production incidents. \n\nYou know those moments when you're debugging at 2am and think \"we should've caught this earlier\"? That's what PatchPulse is for. It's the tool I wish I had when I was managing Kubernetes clusters at scale.\n\nI built this in my spare time, iterating based on real problems I've faced. It's not perfect, but it's useful, and I'm sharing it because I think other teams might find it helpful too.\n\n**Want to chat?**\n- 📧 Email: amarkdotdev@gmail.com\n- 🐙 GitHub: [@amarkdotdev](https://github.com/amarkdotdev)\n- ☕ Buy Me a Coffee: [buymeacoffee.com/aaronmark](https://buymeacoffee.com/aaronmark) (if PatchPulse saves you from a late-night incident, consider it 😊)\n\n---\n\n## 🙏 Thanks\n\nThis project wouldn't exist without the open source community. Special shoutout to everyone who's contributed, reported bugs, or just used PatchPulse and gave feedback.\n\nBuilt with:\n- **FastAPI** - Because Python web frameworks don't have to be slow\n- **PostgreSQL** - Reliable and battle-tested\n- **Go** - For the Kubernetes agent (because sometimes you need speed)\n- **Docker** - Makes deployment actually bearable\n- **Kubernetes** - The thing we're all trying to make safer\n\n---\n\n<div align=\"center\">\n\n**🔓 Open Source | 🤖 Bring Your Own LLM | 🚀 Self-Hosted**\n\n**Made with ❤️ in Israel for the Kubernetes community worldwide**\n\n[⭐ Star on GitHub](https://github.com/amarkdotdev/patchpulse) • [📖 Documentation](https://patchpulse.dev) • [☕ Buy Me a Coffee](https://buymeacoffee.com/aaronmark) • [🐛 Report Bug](https://github.com/amarkdotdev/patchpulse/issues)\n\n</div>\n"}, "db30f1f3339bbdc8a726832e445b56fb36c8de9f": {"t": 1785764233.2593954, "n": 27514, "h": "c9f5a79cb17d7c76", "c": "# PatchPulse\n\n<div align=\"center\">\n\n**🔓 100% Open Source | 🤖 Bring Your Own LLM | 🚀 Self-Hosted Kubernetes Risk Analysis**\n\n[![License](https://img.shields.io/badge/license-Non--Commercial-blue.svg)](LICENSE)\n[![GitHub stars](https://img.shields.io/github/stars/amarkdotdev/patchpulse?style=social)](https://github.com/amarkdotdev/patchpulse)\n[![Website](https://img.shields.io/badge/website-patchpulse.dev-blue)](https://patchpulse.dev)\n[![Buy Me a Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-☕-yellow)](https://buymeacoffee.com/aaronmark)\n\n**Prevent production incidents before they happen**\n\n[Quick Start](#-quick-start) • [Documentation](#-documentation) • [Features](#-key-features) • [Support](#-support)\n\n</div>\n\n---\n\n## 🎯 What is PatchPulse?\n\nPatchPulse is a self-hosted, open-source solution that prevents production incidents by analyzing infrastructure changes and cluster signals before deployment. It combines rule-based guardrails with AI-powered analysis to provide explainable risk scores and automated enforcement.\n\n### Why PatchPulse?\n\n- **🛡️ Prevent Incidents**: Catch risky changes before they reach production\n- **🔍 Explainable Decisions**: Understand why changes are flagged with detailed reasoning\n- **🤖 AI-Powered**: Optional AI analysis for security scanning and recommendations\n- **⚡ Real-Time**: Instant notifications and WebSocket updates\n- **🔓 100% Open Source**: No vendor lock-in, full control over your data\n- **🏠 Self-Hosted**: Your data stays on your infrastructure\n\n---\n\n## ✨ Key Features\n\n### Core Capabilities\n\n- **🔓 Fully Open Source** - Non-commercial license, no vendor lock-in\n- **🤖 Bring Your Own LLM** - Use OpenAI, DeepSeek, Claude, Gemini, or any OpenAI-compatible API\n- **🏠 Self-Hosted** - Your data stays on your infrastructure\n- **🛡️ 11+ Guardrails** - Rule-based checks for Kubernetes best practices\n- **🧠 AI-Powered Analysis** - Security scanning, recommendations, incident prediction\n- **⚡ Real-Time** - WebSocket updates and instant notifications\n- **🔌 Integrations** - GitHub, GitLab, Slack, Teams, PagerDuty, Email\n- **📊 Enterprise Features** - Admission webhooks, policy bundles, SBOM verification, multi-tenancy\n\n### Guardrails Included\n\n1. **Resource Limits** - Ensures CPU/memory limits are set\n2. **Resource Requests** - Validates resource requests are configured\n3. **Readiness Probes** - Checks for readiness probe configuration\n4. **Liveness Probes** - Validates liveness probe setup\n5. **Security Context** - Enforces security context settings\n6. **Image Tags** - Prevents `latest` tag usage\n7. **Namespace Validation** - Ensures proper namespace usage\n8. **Service Account** - Validates service account configuration\n9. **Network Policies** - Checks network policy compliance\n10. **Resource Quotas** - Validates resource quota adherence\n11. **Pod Disruption Budgets** - Ensures PDB configuration\n\n---\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- **Docker** (running) - Required for containerized deployment\n- **Python 3.11+** - For local development\n- **Go 1.21+** - For agent development (optional)\n- **kubectl** - For Kubernetes integration (optional)\n\n### Installation Steps\n\n#### 1. Clone the Repository\n\n```bash\ngit clone https://github.com/amarkdotdev/patchpulse.git\ncd patchpulse\n```\n\n#### 2. Configure Your LLM Provider (Optional)\n\nPatchPulse supports multiple AI providers. **You only need to provide an API key for ONE provider:**\n\n```bash\n# Create .env file\ntouch .env\n\n# Option 1: OpenAI (recommended for best results)\necho \"OPENAI_API_KEY=sk-your-key-here\" >> .env\n\n# Option 2: DeepSeek (cost-effective alternative)\n# echo \"DEEPSEEK_API_KEY=sk-your-key-here\" >> .env\n\n# Option 3: Claude (Anthropic)\n# echo \"ANTHROPIC_API_KEY=sk-ant-your-key-here\" >> .env\n# Note: Requires: pip install anthropic\n\n# Option 4: Google Gemini\n# echo \"GEMINI_API_KEY=your-key-here\" >> .env\n# Note: Requires: pip install google-generativeai\n\n# Optionally specify which provider to use (defaults to first available)\n# echo \"AI_PROVIDER=openai\" >> .env\n```\n\n**💡 No LLM? No Problem!** PatchPulse works without AI - you'll get rule-based guardrails and risk scoring. AI features will be disabled gracefully.\n\n#### 3. Start PatchPulse\n\n```bash\n# Start all services\ndocker compose up -d\n\n# Check logs\ndocker compose logs -f backend\n\n# Wait for services to be ready (about 10-15 seconds)\n```\n\n#### 4. Access the Application\n\nOnce PatchPulse is running, access it at:\n\n- **Dashboard**: http://localhost:8000/dashboard\n  - Main user interface for monitoring decisions, viewing analytics, and managing configurations\n  - Real-time updates via WebSocket\n  - Risk visualization and decision history\n\n- **API Documentation**: http://localhost:8000/docs\n  - Interactive Swagger/OpenAPI documentation\n  - Test API endpoints directly from the browser\n  - Full API reference\n\n- **Health Check**: http://localhost:8000/health\n  - Service health status\n  - Database connectivity check\n\n- **API Root**: http://localhost:8000/api\n  - API information and available endpoints\n\n#### 5. Start Using PatchPulse\n\n1. **Access the Dashboard**: Open http://localhost:8000/dashboard in your browser\n2. **View Decisions**: See real-time risk analysis and decisions\n3. **Configure Integrations**: Set up GitHub, GitLab, Slack, or other integrations via the API\n4. **Monitor Analytics**: Track risk trends, blocked changes, and system health\n\n**Note**: The dashboard is the main interface for PatchPulse. The website (patchpulse.dev) is a separate marketing site and not part of this repository.\n\n---\n\n## 🔄 How PatchPulse Works\n\n### Deployment Models\n\nPatchPulse can be deployed in two ways:\n\n#### Option 1: Standalone Mode (Recommended for Getting Started)\n\n**Backend runs separately** (Docker Compose, VM, or anywhere):\n- Backend service runs independently\n- Agent runs **outside** your Kubernetes cluster\n- Agent connects to your cluster using `kubeconfig`\n- Best for: Testing, development, or when you don't want to deploy into your cluster\n\n```bash\n# 1. Start backend (runs anywhere)\ndocker compose up -d\n\n# 2. Run agent locally (connects to your cluster via kubeconfig)\ncd app/agent\nexport BACKEND_URL=http://localhost:8000\nexport KUBECONFIG=$HOME/.kube/config  # Points to your cluster\ngo run cmd/agent/main.go\n```\n\n#### Option 2: In-Cluster Mode (Production)\n\n**Both backend and agent run inside Kubernetes**:\n- Backend deployed as a Kubernetes Deployment\n- Agent deployed in the same or different namespace\n- Agent uses in-cluster config (ServiceAccount)\n- Best for: Production deployments, full integration\n\n```bash\n# Deploy both backend and agent to your cluster\nhelm install patchpulse-backend ./helm/backend --namespace patchpulse\nhelm install patchpulse-agent ./helm/agent --namespace patchpulse\n```\n\n### How It Analyzes Your Changes\n\nPatchPulse works in **two ways**:\n\n#### 1. **Git Integration** (Pre-Deployment Analysis)\n- Monitors GitHub/GitLab PRs/MRs\n- Analyzes Kubernetes manifests in diffs\n- Evaluates guardrails **before** code is merged\n- Sends notifications if risky changes detected\n\n```bash\n# Example: PR with risky deployment.yaml\n# PatchPulse detects: \"Missing resource limits\"\n# → Risk score: 50\n# → Decision: Advisory (allows, but warns)\n```\n\n#### 2. **Cluster Monitoring** (Post-Deployment)\n- Agent watches your Kubernetes cluster\n- Collects deployment signals, pod events, node status\n- Detects issues in running workloads\n- Provides real-time cluster health insights\n\n### Complete Workflow\n\n```\n┌─────────────────┐\n│  Developer      │\n│  Creates PR     │\n└────────┬────────┘\n         │\n         ▼\n┌─────────────────┐     ┌──────────────────┐\n│  Git Integration│────▶│  PatchPulse      │\n│  (GitHub/GitLab)│     │  Backend         │\n└─────────────────┘     │  (FastAPI)       │\n                        └────────┬─────────┘\n                                 │\n                        ┌────────▼─────────┐\n                        │  Policy Engine   │\n                        │  + AI Analysis   │\n                        └────────┬─────────┘\n                                 │\n                        ┌────────▼─────────┐\n                        │  Risk Score      │\n                        │  Decision        │\n                        └────────┬─────────┘\n                                 │\n         ┌───────────────────────┼───────────────────────┐\n         │                       │                       │\n         ▼                       ▼                       ▼\n┌─────────────────┐    ┌─────────────────┐   ┌─────────────────┐\n│  Notification   │    │  Dashboard       │   │  Kubernetes     │\n│  (Slack/Email)  │    │  (Web UI)        │   │  Agent          │\n└─────────────────┘    └─────────────────┘   └────────┬────────┘\n                                                       │\n                                                       ▼\n                                              ┌─────────────────┐\n                                              │  Your K8s       │\n                                              │  Cluster        │\n                                              └─────────────────┘\n```\n\n### Connecting to Your Kubernetes Cluster\n\n#### For Standalone Mode:\n\n1. **Ensure you have access to your cluster:**\n```bash\n# Test cluster access\nkubectl get nodes\n\n# If using a remote cluster, make sure kubeconfig is set\nexport KUBECONFIG=$HOME/.kube/config\n```\n\n2. **Start the agent pointing to your cluster:**\n```bash\n# The agent will automatically use your kubeconfig\nexport BACKEND_URL=http://localhost:8000  # Where backend is running\ncd app/agent\ngo run cmd/agent/main.go\n```\n\n#### For In-Cluster Mode:\n\n1. **Deploy PatchPulse to your cluster:**\n```bash\n# Create namespace\nkubectl create namespace patchpulse\n\n# Deploy backend\nhelm install patchpulse-backend ./helm/backend \\\n  --namespace patchpulse \\\n  --set env.DATABASE_URL=\"postgresql://...\"\n\n# Deploy agent (automatically connects to cluster)\nhelm install patchpulse-agent ./helm/agent \\\n  --namespace patchpulse \\\n  --set env.BACKEND_URL=\"http://patchpulse-backend:8000\"\n```\n\n2. **The agent automatically uses in-cluster config** (no kubeconfig needed)\n\n### What Gets Analyzed?\n\n#### From Git (PR/MR Analysis):\n- Kubernetes manifests (Deployments, Services, ConfigMaps, etc.)\n- Changes to resource limits, requests, probes\n- Security context changes\n- Image tag updates\n- Network policy changes\n\n#### From Cluster (Agent Monitoring):\n- Deployment availability and replica counts\n- Pod restart counts\n- Node readiness status\n- Warning events\n- Resource utilization trends\n\n---\n\n## 📖 Table of Contents\n\n- [Architecture](#-architecture)\n- [Configuration](#-configuration)\n- [LLM Provider Setup](#-llm-provider-setup)\n- [API Usage](#-api-usage)\n- [Deployment](#-deployment)\n- [Development](#-development)\n- [Use Cases](#-use-cases)\n- [Contributing](#-contributing)\n- [Support](#-support)\n- [License](#-license)\n\n---\n\n## 🏗️ Architecture\n\n### Components\n\n#### 1. Backend (FastAPI)\n- REST API for change events and decisions\n- Policy engine with 11+ guardrails\n- AI-powered risk analysis (bring your own LLM!)\n- PostgreSQL database for persistence\n- WebSocket support for real-time updates\n\n#### 2. Agent (Go)\n- Kubernetes cluster monitoring\n- Resource snapshotting\n- Event watching\n- Least-privilege RBAC\n\n#### 3. Git Integrations\n- GitHub PR analysis\n- GitLab MR analysis\n- Diff parsing and manifest extraction\n\n#### 4. Notification Integrations\n- Slack notifications with interactive approval buttons\n- Email notifications\n- Microsoft Teams integration\n- PagerDuty integration\n\n#### 5. Dashboard UI (Primary Interface)\n- Real-time decision monitoring via WebSocket\n- Risk visualization and analytics\n- Decision history and filtering\n- Export functionality (CSV/JSON)\n- Accessible at `/dashboard` endpoint\n\n### Data Flow\n\n```\n1. Developer creates PR/MR → Git integration detects change\n2. Change event sent to backend → Policy engine evaluates\n3. AI analysis runs (if configured) → Security scan, recommendations, predictions\n4. Risk score calculated (0-100) → Decision made (allow/block)\n5. Notification sent to Slack/Teams → Decision stored in database\n6. Dashboard updates in real-time via WebSocket\n```\n\n### System Architecture Diagram\n\n```\n┌─────────────┐     ┌──────────────┐     ┌─────────────┐\n│   GitHub    │────▶│ Git Poller   │────▶│  Backend    │\n│   GitLab    │     │              │     │  (FastAPI)  │\n└─────────────┘     └──────────────┘     └──────┬──────┘\n                                                 │\n┌─────────────┐     ┌──────────────┐             │\n│ Kubernetes  │────▶│   Agent     │─────────────┘\n│   Cluster   │     │    (Go)     │\n└─────────────┘     └──────────────┘\n                                                 │\n┌─────────────┐     ┌──────────────┐     ┌─────▼──────┐\n│   Slack     │◀────│ Notifications│◀────│ PostgreSQL │\n│   Teams     │     │              │     │  Database  │\n│  PagerDuty  │     └──────────────┘     └────────────┘\n│   Email     │\n└─────────────┘\n```\n\n---\n\n## 🔧 Configuration\n\n### Environment Variables\n\nCreate a `.env` file in the root directory:\n\n```bash\n# Database\nDATABASE_URL=postgresql://patchpulse:patchpulse@postgres:5432/patchpulse\n\n# Policy Mode (advisory or enforce)\nPOLICY_MODE=advisory\n\n# Logging\nLOG_LEVEL=INFO\n\n# AI Provider - Choose ONE (see LLM Provider Setup section)\nOPENAI_API_KEY=your_openai_api_key\n# OR\n# DEEPSEEK_API_KEY=your_deepseek_api_key\n# OR\n# ANTHROPIC_API_KEY=your_anthropic_api_key\n# OR\n# GEMINI_API_KEY=your_gemini_api_key\n\n# Optional: Specify which provider to use (defaults to first available)\nAI_PROVIDER=openai\n\n# Git Integration\nGITHUB_TOKEN=your_github_token\nGITHUB_REPOS=owner/repo1,owner/repo2\nGITLAB_TOKEN=your_gitlab_token\nGITLAB_PROJECTS=12345,67890\n\n# JWT Secret (auto-generated if not set)\nJWT_SECRET_KEY=your_jwt_secret\n```\n\n### Policy Modes\n\n- **`advisory`**: Logs decisions but doesn't block changes (default)\n  - Best for: Testing, gradual rollout, learning mode\n  - All decisions are logged and visible in dashboard\n  - No changes are blocked\n\n- **`enforce`**: Blocks high-risk changes (score ≥ 70)\n  - Best for: Production environments\n  - High-risk changes are automatically blocked\n  - Requires manual approval for blocked changes\n\n---\n\n## 🤖 LLM Provider Setup\n\nPatchPulse is **100% open source** and supports **bring your own LLM**. You can use any of these providers:\n\n### Supported Providers\n\n| Provider | Cost | Quality | Setup |\n|----------|------|---------|-------|\n| **OpenAI** | $$$ | ⭐⭐⭐⭐⭐ | `OPENAI_API_KEY=sk-...` |\n| **DeepSeek** | $ | ⭐⭐⭐⭐ | `DEEPSEEK_API_KEY=sk-...` |\n| **Claude** | $$$ | ⭐⭐⭐⭐⭐ | `ANTHROPIC_API_KEY=sk-ant-...` |\n| **Gemini** | $$ | ⭐⭐⭐⭐ | `GEMINI_API_KEY=...` |\n\n### OpenAI\n\n```bash\nexport OPENAI_API_KEY=sk-your-key-here\n# Or in .env file:\necho \"OPENAI_API_KEY=sk-your-key-here\" >> .env\n```\n\n**Models**: Uses `gpt-4o-mini` by default (cost-effective). You can modify `ai_analyzer.py` to use other models.\n\n### DeepSeek (Recommended for Cost-Conscious Users)\n\n```bash\nexport DEEPSEEK_API_KEY=sk-your-key-here\n# Or in .env file:\necho \"DEEPSEEK_API_KEY=sk-your-key-here\" >> .env\n```\n\n**Models**: Uses `deepseek-chat` by default. OpenAI-compatible API.\n\n### Claude (Anthropic)\n\n```bash\n# First install the package\npip install anthropic\n\nexport ANTHROPIC_API_KEY=sk-ant-your-key-here\n# Or in .env file:\necho \"ANTHROPIC_API_KEY=sk-ant-your-key-here\" >> .env\n```\n\n**Models**: Uses `claude-3-5-sonnet-20241022` by default.\n\n### Google Gemini\n\n```bash\n# First install the package\npip install google-generativeai\n\nexport GEMINI_API_KEY=your-key-here\n# Or in .env file:\necho \"GEMINI_API_KEY=your-key-here\" >> .env\n```\n\n**Models**: Uses `gemini-1.5-pro` by default.\n\n### Using a Custom OpenAI-Compatible API\n\nPatchPulse supports any OpenAI-compatible API endpoint (Ollama, LocalAI, vLLM, etc.):\n\n```bash\n# Set a dummy API key (not used for local endpoints)\nexport OPENAI_API_KEY=not-used\n\n# Set your custom endpoint\nexport OPENAI_BASE_URL=http://localhost:11434/v1  # Ollama example\n# Or\nexport OPENAI_BASE_URL=http://localhost:8080/v1   # LocalAI example\n\n# Or in .env file:\necho \"OPENAI_API_KEY=not-used\" >> .env\necho \"OPENAI_BASE_URL=http://localhost:11434/v1\" >> .env\n```\n\n**Examples:**\n- **Ollama**: `OPENAI_BASE_URL=http://localhost:11434/v1`\n- **LocalAI**: `OPENAI_BASE_URL=http://localhost:8080/v1`\n- **vLLM**: `OPENAI_BASE_URL=http://localhost:8000/v1`\n- **Any OpenAI-compatible service**: Just set the base URL!\n\nThe system will automatically use your custom endpoint with the OpenAI client.\n\n### No LLM Required\n\n**PatchPulse works perfectly without any LLM!** If no API key is provided:\n- ✅ All rule-based guardrails work\n- ✅ Risk scoring works\n- ✅ All integrations work\n- ✅ Dashboard works\n- ⚠️ AI-powered features are disabled (security scanning, recommendations, predictions)\n\n---\n\n## 📊 API Usage\n\n### Create Change Event\n\n```bash\ncurl -X POST http://localhost:8000/api/v1/change-events \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"source\": \"github\",\n    \"repo\": \"org/repo\",\n    \"sha\": \"abc123\",\n    \"pr_number\": 42,\n    \"branch\": \"feature-branch\",\n    \"files\": [\"k8s/deployment.yaml\"],\n    \"diff_hunks\": [{\n      \"file\": \"k8s/deployment.yaml\",\n      \"hunk\": \"- limits:\\n  cpu: 500m\"\n    }],\n    \"timestamp\": \"2026-01-01T00:00:00Z\"\n  }'\n```\n\n### Get Decisions\n\n```bash\ncurl http://localhost:8000/api/v1/decisions?limit=10\n```\n\n### Get Analytics\n\n```bash\ncurl http://localhost:8000/api/v1/analytics/summary\n```\n\n### Get Decision by ID\n\n```bash\ncurl http://localhost:8000/api/v1/decisions/{decision_id}\n```\n\n### Filter Decisions\n\n```bash\n# Filter by risk score\ncurl \"http://localhost:8000/api/v1/decisions?min_risk=50&max_risk=100\"\n\n# Filter by source\ncurl \"http://localhost:8000/api/v1/decisions?source=github\"\n\n# Filter by date range\ncurl \"http://localhost:8000/api/v1/decisions?start_date=2026-01-01&end_date=2026-01-31\"\n```\n\nSee `/docs` for interactive API documentation.\n\n---\n\n## 🚢 Deployment\n\n### Docker Compose (Recommended for Quick Start)\n\n```bash\ndocker compose up -d\n```\n\n### Kubernetes (Helm)\n\n**Option 1: Using your `.env` file (Recommended)**\n\n```bash\n# Create a values file from your .env\n# This reads your .env file and creates Helm values\ncat > /tmp/patchpulse-values.yaml <<EOF\nenv:\n  DATABASE_URL: \"postgresql://patchpulse:patchpulse@postgres:5432/patchpulse\"\n  POLICY_MODE: \"advisory\"\n  LOG_LEVEL: \"INFO\"\n  OPENAI_API_KEY: \"$(grep OPENAI_API_KEY .env | cut -d '=' -f2)\"\n  DEEPSEEK_API_KEY: \"$(grep DEEPSEEK_API_KEY .env | cut -d '=' -f2 || echo '')\"\n  ANTHROPIC_API_KEY: \"$(grep ANTHROPIC_API_KEY .env | cut -d '=' -f2 || echo '')\"\n  GEMINI_API_KEY: \"$(grep GEMINI_API_KEY .env | cut -d '=' -f2 || echo '')\"\nEOF\n\n# Install backend using values from .env\nhelm install patchpulse-backend ./helm/backend \\\n  --namespace patchpulse \\\n  --create-namespace \\\n  --values /tmp/patchpulse-values.yaml\n\n# Install agent\nhelm install patchpulse-agent ./helm/agent \\\n  --namespace patchpulse \\\n  --set env.BACKEND_URL=http://patchpulse-backend:8000\n```\n\n**Option 2: Using --set-file (Alternative)**\n\n```bash\n# Install backend with API key from .env file\nhelm install patchpulse-backend ./helm/backend \\\n  --namespace patchpulse \\\n  --create-namespace \\\n  --set env.OPENAI_API_KEY=\"$(grep OPENAI_API_KEY .env | cut -d '=' -f2)\" \\\n  --set env.POLICY_MODE=advisory\n\n# Install agent\nhelm install patchpulse-agent ./helm/agent \\\n  --namespace patchpulse \\\n  --set env.BACKEND_URL=http://patchpulse-backend:8000\n```\n\n**Option 3: Manual values override**\n\nEdit `helm/backend/values.yaml` and add your API keys to the `env` section, then install:\n\n```bash\nhelm install patchpulse-backend ./helm/backend \\\n  --namespace patchpulse \\\n  --create-namespace\n```\n\n### Production Considerations\n\n- Use environment variables for secrets (never hardcode)\n- Set up proper TLS/SSL certificates\n- Configure database backups\n- Set up monitoring and alerting\n- Use a managed PostgreSQL database for production\n- Configure rate limiting\n- Set up log aggregation\n- Enable audit logging\n\n---\n\n## 🛠️ Development\n\n### Local Development Setup\n\n```bash\n# Backend\ncd app/backend\npython -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\npip install -r requirements.txt\nuvicorn main:app --reload\n\n# Agent\ncd app/agent\ngo run cmd/agent/main.go\n\n# Git Integration\ncd app/integrations/git\npython poller.py\n```\n\n### Running Tests\n\n```bash\n# Unit tests\ncd app/backend\npytest tests/\n\n# Integration tests\ndocker compose up -d\n./test_api_endpoints.sh\n```\n\n### Project Structure\n\n```\npatchpulse/\n├── app/                    # Application code\n│   ├── backend/           # FastAPI backend service\n│   │   ├── main.py        # Main application entry point\n│   │   ├── models.py      # Pydantic models and SQLAlchemy ORM\n│   │   ├── database.py    # Database connection and setup\n│   │   ├── policy_engine.py # Policy evaluation and guardrails\n│   │   ├── ai_analyzer.py # AI-powered risk analysis (BYO LLM!)\n│   │   ├── ai_features.py # Advanced AI features\n│   │   ├── auth.py        # Authentication system\n│   │   └── requirements.txt\n│   ├── agent/             # Kubernetes agent (Go)\n│   │   ├── cmd/agent/     # Agent main application\n│   │   └── Dockerfile\n│   ├── integrations/     # External integrations\n│   │   ├── git/           # GitHub/GitLab integration\n│   │   ├── slack/         # Slack notifications\n│   │   ├── teams/         # Microsoft Teams integration\n│   │   ├── pagerduty/     # PagerDuty integration\n│   │   └── email/         # Email notifications\n│   └── ui/                # Dashboard UI (served at /dashboard)\n├── docs/                  # Technical documentation\n├── helm/                  # Kubernetes Helm charts\n├── docker-compose.yml     # Local development setup\n└── README.md             # This file\n```\n\n---\n\n## 💼 Use Cases\n\n### 1. CI/CD Pipeline Integration\n\nIntegrate PatchPulse into your CI/CD pipeline to automatically analyze PRs:\n\n```yaml\n# GitHub Actions example\n- name: Analyze with PatchPulse\n  run: |\n    curl -X POST $PATCHPULSE_URL/api/v1/change-events \\\n      -H \"Content-Type: application/json\" \\\n      -d @change-event.json\n```\n\n### 2. Pre-Deployment Validation\n\nValidate Kubernetes manifests before deployment:\n\n```bash\n# Analyze deployment manifests\nkubectl apply --dry-run=client -f deployment.yaml | \\\n  patchpulse analyze --source=manual\n```\n\n### 3. Compliance Auditing\n\nTrack compliance with Kubernetes best practices:\n\n```bash\n# Get compliance report\ncurl http://localhost:8000/api/v1/analytics/compliance\n```\n\n### 4. Incident Prevention\n\nPrevent production incidents by catching risky changes:\n\n- Missing resource limits\n- Security misconfigurations\n- Image tag issues\n- Network policy violations\n\n### 5. Team Education\n\nUse PatchPulse to educate teams on Kubernetes best practices:\n\n- Real-time feedback on PRs\n- Detailed explanations of guardrail violations\n- Historical analytics on common mistakes\n\n---\n\n## 🛡️ Security\n\n- **API keys never exposed** in logs or responses\n- **Least-privilege RBAC** for agent\n- **Encrypted database** connections\n- **TLS** for all API communications\n- **Audit logging** for all decisions\n- **Rate limiting** on API endpoints\n- **Self-hosted** - your data stays on your infrastructure\n\nSee [SECURITY.md](SECURITY.md) for detailed security information.\n\n---\n\n## 🤝 Contributing\n\nWe welcome contributions! PatchPulse is 100% open source and community-driven.\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n### Areas for Contribution\n\n- 🐛 Bug fixes\n- ✨ New features\n- 📚 Documentation improvements\n- 🧪 Test coverage\n- 🌐 Translations\n- 🎨 UI/UX improvements\n- 🔌 New integrations\n\n---\n\n## 📄 License\n\nThis project is licensed under the **PatchPulse Non-Commercial License** - see the [LICENSE](LICENSE) file for details.\n\n**✅ Permitted Uses:**\n- Personal use\n- Educational use\n- Research and development\n- Internal use within non-profit organizations\n- Contributing to the PatchPulse project\n- Forking and modifying for personal/educational purposes\n\n**❌ Prohibited Uses:**\n- Commercial use (selling, licensing, or providing as a service)\n- Use in commercial products or services\n- Reselling or redistributing for profit\n- Use by for-profit companies without explicit written permission\n\n**💼 Commercial Licensing:**\nFor commercial use, please contact us to obtain a commercial license. Commercial licenses are available for:\n- SaaS providers\n- Enterprise deployments\n- Commercial products incorporating PatchPulse\n- Consulting services using PatchPulse\n\n**Contact:** amarkdotdev@gmail.com\n\nThis license protects the open-source nature of PatchPulse while ensuring commercial use requires proper licensing.\n\n---\n\n## 🆘 Support\n\n### Getting Help\n\n- **Documentation**: http://localhost:8000/docs (when running locally)\n- **Website**: https://patchpulse.dev\n- **Issues**: https://github.com/amarkdotdev/patchpulse/issues\n- **Discussions**: https://github.com/amarkdotdev/patchpulse/discussions\n- **Email**: amarkdotdev@gmail.com\n\n### Community\n\n- ⭐ Star us on GitHub if you find PatchPulse useful!\n- 🐛 Report bugs via GitHub Issues\n- 💡 Suggest features via GitHub Discussions\n- 📖 Improve documentation via Pull Requests\n\n---\n\n## ☕ Support the Project\n\nIf PatchPulse has been helpful to you, consider supporting the project:\n\n**[☕ Buy Me a Coffee](https://buymeacoffee.com/aaronmark)**\n\nYour support helps maintain and improve PatchPulse. Thank you! 🙏\n\n---\n\n## 🎯 Roadmap\n\n- [ ] Multi-tenant support (in progress)\n- [ ] Custom guardrail DSL\n- [ ] Integration with more Git providers (Bitbucket, Azure DevOps)\n- [ ] Additional AI provider support\n- [ ] Compliance reporting (SOC2, ISO27001)\n- [ ] Enhanced documentation\n- [ ] Local LLM support (Ollama, LocalAI)\n- [ ] Webhook support for real-time PR analysis\n- [ ] Custom risk scoring algorithms\n- [ ] Policy templates library\n\n---\n\n## 👨‍💻 About the Creator\n\nPatchPulse was created by **Aaron Mark**, a passionate DevOps engineer from **Israel** 🇮🇱. \n\nAfter experiencing countless production incidents that could have been prevented, Aaron built PatchPulse to help engineering teams ship with confidence. Israel is Aaron's home, and it's from this innovative tech ecosystem that PatchPulse was born.\n\nThe project reflects the values of the Israeli tech community: innovation, pragmatism, and a focus on solving real problems that engineers face every day.\n\n**Connect with Aaron:**\n- 📧 Email: amarkdotdev@gmail.com\n- 🐙 GitHub: [@amarkdotdev](https://github.com/amarkdotdev)\n- ☕ Buy Me a Coffee: [buymeacoffee.com/aaronmark](https://buymeacoffee.com/aaronmark)\n\n---\n\n## 🙏 Acknowledgments\n\nBuilt with ❤️ by the open source community. Special thanks to all contributors!\n\n### Technologies Used\n\n- **FastAPI** - Modern Python web framework\n- **PostgreSQL** - Robust relational database\n- **Go** - High-performance Kubernetes agent\n- **React/Vue** - Dashboard UI (if applicable)\n- **Docker** - Containerization\n- **Kubernetes** - Container orchestration\n\n---\n\n<div align=\"center\">\n\n**🔓 Open Source | 🤖 Bring Your Own LLM | 🚀 Self-Hosted**\n\n**Made with ❤️ in Israel for the Kubernetes community worldwide**\n\n[⭐ Star on GitHub](https://github.com/amarkdotdev/patchpulse) • [📖 Documentation](https://patchpulse.dev) • [☕ Buy Me a Coffee](https://buymeacoffee.com/aaronmark) • [🐛 Report Bug](https://github.com/amarkdotdev/patchpulse/issues)\n\n</div>\n"}, "bd4d2f2aef70e1d14bac6f2227e6bd152009c934": {"t": 1785764234.936992, "n": 22531, "h": "6f7713c16bd91985", "c": "# PatchPulse\n\n<div align=\"center\">\n\n**🔓 100% Open Source | 🤖 Bring Your Own LLM | 🚀 Self-Hosted Kubernetes Risk Analysis**\n\n[![License](https://img.shields.io/badge/license-Non--Commercial-blue.svg)](LICENSE)\n[![GitHub stars](https://img.shields.io/github/stars/amarkdotdev/patchpulse?style=social)](https://github.com/amarkdotdev/patchpulse)\n[![Website](https://img.shields.io/badge/website-patchpulse.dev-blue)](https://patchpulse.dev)\n[![Buy Me a Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-☕-yellow)](https://buymeacoffee.com/aaronmark)\n\n**Prevent production incidents before they happen**\n\n[Quick Start](#-quick-start) • [Documentation](#-documentation) • [Features](#-key-features) • [Support](#-support)\n\n</div>\n\n---\n\n## 🎯 What is PatchPulse?\n\nPatchPulse is a self-hosted, open-source solution that prevents production incidents by analyzing infrastructure changes and cluster signals before deployment. It combines rule-based guardrails with AI-powered analysis to provide explainable risk scores and automated enforcement.\n\n### Why PatchPulse?\n\n- **🛡️ Prevent Incidents**: Catch risky changes before they reach production\n- **🔍 Explainable Decisions**: Understand why changes are flagged with detailed reasoning\n- **🤖 AI-Powered**: Optional AI analysis for security scanning and recommendations\n- **⚡ Real-Time**: Instant notifications and WebSocket updates\n- **🔓 100% Open Source**: No vendor lock-in, full control over your data\n- **🏠 Self-Hosted**: Your data stays on your infrastructure\n\n---\n\n## ✨ Key Features\n\n### Core Capabilities\n\n- **🔓 Fully Open Source** - Non-commercial license, no vendor lock-in\n- **🤖 Bring Your Own LLM** - Use OpenAI, DeepSeek, Claude, Gemini, or any OpenAI-compatible API\n- **🏠 Self-Hosted** - Your data stays on your infrastructure\n- **🛡️ 11+ Guardrails** - Rule-based checks for Kubernetes best practices\n- **🧠 AI-Powered Analysis** - Security scanning, recommendations, incident prediction\n- **⚡ Real-Time** - WebSocket updates and instant notifications\n- **🔌 Integrations** - GitHub, GitLab, Slack, Teams, PagerDuty, Email\n- **📊 Enterprise Features** - Admission webhooks, policy bundles, SBOM verification, multi-tenancy\n\n### Guardrails Included\n\n1. **Resource Limits** - Ensures CPU/memory limits are set\n2. **Resource Requests** - Validates resource requests are configured\n3. **Readiness Probes** - Checks for readiness probe configuration\n4. **Liveness Probes** - Validates liveness probe setup\n5. **Security Context** - Enforces security context settings\n6. **Image Tags** - Prevents `latest` tag usage\n7. **Namespace Validation** - Ensures proper namespace usage\n8. **Service Account** - Validates service account configuration\n9. **Network Policies** - Checks network policy compliance\n10. **Resource Quotas** - Validates resource quota adherence\n11. **Pod Disruption Budgets** - Ensures PDB configuration\n\n---\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- **Docker** (running) - Required for containerized deployment\n- **Python 3.11+** - For local development\n- **Go 1.21+** - For agent development (optional)\n- **kubectl** - For Kubernetes integration (optional)\n\n### Installation Steps\n\n#### 1. Clone the Repository\n\n```bash\ngit clone https://github.com/amarkdotdev/patchpulse.git\ncd patchpulse\n```\n\n#### 2. Configure Your LLM Provider (Optional)\n\nPatchPulse supports multiple AI providers. **You only need to provide an API key for ONE provider:**\n\n```bash\n# Create .env file\ntouch .env\n\n# Option 1: OpenAI (recommended for best results)\necho \"OPENAI_API_KEY=sk-your-key-here\" >> .env\n\n# Option 2: DeepSeek (cost-effective alternative)\n# echo \"DEEPSEEK_API_KEY=sk-your-key-here\" >> .env\n\n# Option 3: Claude (Anthropic)\n# echo \"ANTHROPIC_API_KEY=sk-ant-your-key-here\" >> .env\n# Note: Requires: pip install anthropic\n\n# Option 4: Google Gemini\n# echo \"GEMINI_API_KEY=your-key-here\" >> .env\n# Note: Requires: pip install google-generativeai\n\n# Optionally specify which provider to use (defaults to first available)\n# echo \"AI_PROVIDER=openai\" >> .env\n```\n\n**💡 No LLM? No Problem!** PatchPulse works without AI - you'll get rule-based guardrails and risk scoring. AI features will be disabled gracefully.\n\n#### 3. Start PatchPulse\n\n```bash\n# Start all services\ndocker compose up -d\n\n# Check logs\ndocker compose logs -f backend\n\n# Wait for services to be ready (about 10-15 seconds)\n```\n\n#### 4. Access the Application\n\nOnce PatchPulse is running, access it at:\n\n- **Dashboard**: http://localhost:8000/dashboard\n  - Main user interface for monitoring decisions, viewing analytics, and managing configurations\n  - Real-time updates via WebSocket\n  - Risk visualization and decision history\n\n- **API Documentation**: http://localhost:8000/docs\n  - Interactive Swagger/OpenAPI documentation\n  - Test API endpoints directly from the browser\n  - Full API reference\n\n- **Health Check**: http://localhost:8000/health\n  - Service health status\n  - Database connectivity check\n\n- **API Root**: http://localhost:8000/api\n  - API information and available endpoints\n\n#### 5. Start Using PatchPulse\n\n1. **Access the Dashboard**: Open http://localhost:8000/dashboard in your browser\n2. **View Decisions**: See real-time risk analysis and decisions\n3. **Configure Integrations**: Set up GitHub, GitLab, Slack, or other integrations via the API\n4. **Monitor Analytics**: Track risk trends, blocked changes, and system health\n\n**Note**: The dashboard is the main interface for PatchPulse. The website (patchpulse.dev) is a separate marketing site and not part of this repository.\n\n---\n\n## 📖 Table of Contents\n\n- [Architecture](#-architecture)\n- [Configuration](#-configuration)\n- [LLM Provider Setup](#-llm-provider-setup)\n- [API Usage](#-api-usage)\n- [Deployment](#-deployment)\n- [Development](#-development)\n- [Use Cases](#-use-cases)\n- [Contributing](#-contributing)\n- [Support](#-support)\n- [License](#-license)\n\n---\n\n## 🏗️ Architecture\n\n### Components\n\n#### 1. Backend (FastAPI)\n- REST API for change events and decisions\n- Policy engine with 11+ guardrails\n- AI-powered risk analysis (bring your own LLM!)\n- PostgreSQL database for persistence\n- WebSocket support for real-time updates\n\n#### 2. Agent (Go)\n- Kubernetes cluster monitoring\n- Resource snapshotting\n- Event watching\n- Least-privilege RBAC\n\n#### 3. Git Integrations\n- GitHub PR analysis\n- GitLab MR analysis\n- Diff parsing and manifest extraction\n\n#### 4. Notification Integrations\n- Slack notifications with interactive approval buttons\n- Email notifications\n- Microsoft Teams integration\n- PagerDuty integration\n\n#### 5. Dashboard UI (Primary Interface)\n- Real-time decision monitoring via WebSocket\n- Risk visualization and analytics\n- Decision history and filtering\n- Export functionality (CSV/JSON)\n- Accessible at `/dashboard` endpoint\n\n### Data Flow\n\n```\n1. Developer creates PR/MR → Git integration detects change\n2. Change event sent to backend → Policy engine evaluates\n3. AI analysis runs (if configured) → Security scan, recommendations, predictions\n4. Risk score calculated (0-100) → Decision made (allow/block)\n5. Notification sent to Slack/Teams → Decision stored in database\n6. Dashboard updates in real-time via WebSocket\n```\n\n### System Architecture Diagram\n\n```\n┌─────────────┐     ┌──────────────┐     ┌─────────────┐\n│   GitHub    │────▶│ Git Poller   │────▶│  Backend    │\n│   GitLab    │     │              │     │  (FastAPI)  │\n└─────────────┘     └──────────────┘     └──────┬──────┘\n                                                 │\n┌─────────────┐     ┌──────────────┐             │\n│ Kubernetes  │────▶│   Agent     │─────────────┘\n│   Cluster   │     │    (Go)     │\n└─────────────┘     └──────────────┘\n                                                 │\n┌─────────────┐     ┌──────────────┐     ┌─────▼──────┐\n│   Slack     │◀────│ Notifications│◀────│ PostgreSQL │\n│   Teams     │     │              │     │  Database  │\n│  PagerDuty  │     └──────────────┘     └────────────┘\n│   Email     │\n└─────────────┘\n```\n\n---\n\n## 🔧 Configuration\n\n### Environment Variables\n\nCreate a `.env` file in the root directory:\n\n```bash\n# Database\nDATABASE_URL=postgresql://patchpulse:patchpulse@postgres:5432/patchpulse\n\n# Policy Mode (advisory or enforce)\nPOLICY_MODE=advisory\n\n# Logging\nLOG_LEVEL=INFO\n\n# AI Provider - Choose ONE (see LLM Provider Setup section)\nOPENAI_API_KEY=your_openai_api_key\n# OR\n# DEEPSEEK_API_KEY=your_deepseek_api_key\n# OR\n# ANTHROPIC_API_KEY=your_anthropic_api_key\n# OR\n# GEMINI_API_KEY=your_gemini_api_key\n\n# Optional: Specify which provider to use (defaults to first available)\nAI_PROVIDER=openai\n\n# Git Integration\nGITHUB_TOKEN=your_github_token\nGITHUB_REPOS=owner/repo1,owner/repo2\nGITLAB_TOKEN=your_gitlab_token\nGITLAB_PROJECTS=12345,67890\n\n# JWT Secret (auto-generated if not set)\nJWT_SECRET_KEY=your_jwt_secret\n```\n\n### Policy Modes\n\n- **`advisory`**: Logs decisions but doesn't block changes (default)\n  - Best for: Testing, gradual rollout, learning mode\n  - All decisions are logged and visible in dashboard\n  - No changes are blocked\n\n- **`enforce`**: Blocks high-risk changes (score ≥ 70)\n  - Best for: Production environments\n  - High-risk changes are automatically blocked\n  - Requires manual approval for blocked changes\n\n---\n\n## 🤖 LLM Provider Setup\n\nPatchPulse is **100% open source** and supports **bring your own LLM**. You can use any of these providers:\n\n### Supported Providers\n\n| Provider | Cost | Quality | Setup |\n|----------|------|---------|-------|\n| **OpenAI** | $$$ | ⭐⭐⭐⭐⭐ | `OPENAI_API_KEY=sk-...` |\n| **DeepSeek** | $ | ⭐⭐⭐⭐ | `DEEPSEEK_API_KEY=sk-...` |\n| **Claude** | $$$ | ⭐⭐⭐⭐⭐ | `ANTHROPIC_API_KEY=sk-ant-...` |\n| **Gemini** | $$ | ⭐⭐⭐⭐ | `GEMINI_API_KEY=...` |\n\n### OpenAI\n\n```bash\nexport OPENAI_API_KEY=sk-your-key-here\n# Or in .env file:\necho \"OPENAI_API_KEY=sk-your-key-here\" >> .env\n```\n\n**Models**: Uses `gpt-4o-mini` by default (cost-effective). You can modify `ai_analyzer.py` to use other models.\n\n### DeepSeek (Recommended for Cost-Conscious Users)\n\n```bash\nexport DEEPSEEK_API_KEY=sk-your-key-here\n# Or in .env file:\necho \"DEEPSEEK_API_KEY=sk-your-key-here\" >> .env\n```\n\n**Models**: Uses `deepseek-chat` by default. OpenAI-compatible API.\n\n### Claude (Anthropic)\n\n```bash\n# First install the package\npip install anthropic\n\nexport ANTHROPIC_API_KEY=sk-ant-your-key-here\n# Or in .env file:\necho \"ANTHROPIC_API_KEY=sk-ant-your-key-here\" >> .env\n```\n\n**Models**: Uses `claude-3-5-sonnet-20241022` by default.\n\n### Google Gemini\n\n```bash\n# First install the package\npip install google-generativeai\n\nexport GEMINI_API_KEY=your-key-here\n# Or in .env file:\necho \"GEMINI_API_KEY=your-key-here\" >> .env\n```\n\n**Models**: Uses `gemini-1.5-pro` by default.\n\n### Using a Custom OpenAI-Compatible API\n\nPatchPulse supports any OpenAI-compatible API endpoint (Ollama, LocalAI, vLLM, etc.):\n\n```bash\n# Set a dummy API key (not used for local endpoints)\nexport OPENAI_API_KEY=not-used\n\n# Set your custom endpoint\nexport OPENAI_BASE_URL=http://localhost:11434/v1  # Ollama example\n# Or\nexport OPENAI_BASE_URL=http://localhost:8080/v1   # LocalAI example\n\n# Or in .env file:\necho \"OPENAI_API_KEY=not-used\" >> .env\necho \"OPENAI_BASE_URL=http://localhost:11434/v1\" >> .env\n```\n\n**Examples:**\n- **Ollama**: `OPENAI_BASE_URL=http://localhost:11434/v1`\n- **LocalAI**: `OPENAI_BASE_URL=http://localhost:8080/v1`\n- **vLLM**: `OPENAI_BASE_URL=http://localhost:8000/v1`\n- **Any OpenAI-compatible service**: Just set the base URL!\n\nThe system will automatically use your custom endpoint with the OpenAI client.\n\n### No LLM Required\n\n**PatchPulse works perfectly without any LLM!** If no API key is provided:\n- ✅ All rule-based guardrails work\n- ✅ Risk scoring works\n- ✅ All integrations work\n- ✅ Dashboard works\n- ⚠️ AI-powered features are disabled (security scanning, recommendations, predictions)\n\n---\n\n## 📊 API Usage\n\n### Create Change Event\n\n```bash\ncurl -X POST http://localhost:8000/api/v1/change-events \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"source\": \"github\",\n    \"repo\": \"org/repo\",\n    \"sha\": \"abc123\",\n    \"pr_number\": 42,\n    \"branch\": \"feature-branch\",\n    \"files\": [\"k8s/deployment.yaml\"],\n    \"diff_hunks\": [{\n      \"file\": \"k8s/deployment.yaml\",\n      \"hunk\": \"- limits:\\n  cpu: 500m\"\n    }],\n    \"timestamp\": \"2026-01-01T00:00:00Z\"\n  }'\n```\n\n### Get Decisions\n\n```bash\ncurl http://localhost:8000/api/v1/decisions?limit=10\n```\n\n### Get Analytics\n\n```bash\ncurl http://localhost:8000/api/v1/analytics/summary\n```\n\n### Get Decision by ID\n\n```bash\ncurl http://localhost:8000/api/v1/decisions/{decision_id}\n```\n\n### Filter Decisions\n\n```bash\n# Filter by risk score\ncurl \"http://localhost:8000/api/v1/decisions?min_risk=50&max_risk=100\"\n\n# Filter by source\ncurl \"http://localhost:8000/api/v1/decisions?source=github\"\n\n# Filter by date range\ncurl \"http://localhost:8000/api/v1/decisions?start_date=2026-01-01&end_date=2026-01-31\"\n```\n\nSee `/docs` for interactive API documentation.\n\n---\n\n## 🚢 Deployment\n\n### Docker Compose (Recommended for Quick Start)\n\n```bash\ndocker compose up -d\n```\n\n### Kubernetes (Helm)\n\n**Option 1: Using your `.env` file (Recommended)**\n\n```bash\n# Create a values file from your .env\n# This reads your .env file and creates Helm values\ncat > /tmp/patchpulse-values.yaml <<EOF\nenv:\n  DATABASE_URL: \"postgresql://patchpulse:patchpulse@postgres:5432/patchpulse\"\n  POLICY_MODE: \"advisory\"\n  LOG_LEVEL: \"INFO\"\n  OPENAI_API_KEY: \"$(grep OPENAI_API_KEY .env | cut -d '=' -f2)\"\n  DEEPSEEK_API_KEY: \"$(grep DEEPSEEK_API_KEY .env | cut -d '=' -f2 || echo '')\"\n  ANTHROPIC_API_KEY: \"$(grep ANTHROPIC_API_KEY .env | cut -d '=' -f2 || echo '')\"\n  GEMINI_API_KEY: \"$(grep GEMINI_API_KEY .env | cut -d '=' -f2 || echo '')\"\nEOF\n\n# Install backend using values from .env\nhelm install patchpulse-backend ./helm/backend \\\n  --namespace patchpulse \\\n  --create-namespace \\\n  --values /tmp/patchpulse-values.yaml\n\n# Install agent\nhelm install patchpulse-agent ./helm/agent \\\n  --namespace patchpulse \\\n  --set env.BACKEND_URL=http://patchpulse-backend:8000\n```\n\n**Option 2: Using --set-file (Alternative)**\n\n```bash\n# Install backend with API key from .env file\nhelm install patchpulse-backend ./helm/backend \\\n  --namespace patchpulse \\\n  --create-namespace \\\n  --set env.OPENAI_API_KEY=\"$(grep OPENAI_API_KEY .env | cut -d '=' -f2)\" \\\n  --set env.POLICY_MODE=advisory\n\n# Install agent\nhelm install patchpulse-agent ./helm/agent \\\n  --namespace patchpulse \\\n  --set env.BACKEND_URL=http://patchpulse-backend:8000\n```\n\n**Option 3: Manual values override**\n\nEdit `helm/backend/values.yaml` and add your API keys to the `env` section, then install:\n\n```bash\nhelm install patchpulse-backend ./helm/backend \\\n  --namespace patchpulse \\\n  --create-namespace\n```\n\n### Production Considerations\n\n- Use environment variables for secrets (never hardcode)\n- Set up proper TLS/SSL certificates\n- Configure database backups\n- Set up monitoring and alerting\n- Use a managed PostgreSQL database for production\n- Configure rate limiting\n- Set up log aggregation\n- Enable audit logging\n\n---\n\n## 🛠️ Development\n\n### Local Development Setup\n\n```bash\n# Backend\ncd app/backend\npython -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\npip install -r requirements.txt\nuvicorn main:app --reload\n\n# Agent\ncd app/agent\ngo run cmd/agent/main.go\n\n# Git Integration\ncd app/integrations/git\npython poller.py\n```\n\n### Running Tests\n\n```bash\n# Unit tests\ncd app/backend\npytest tests/\n\n# Integration tests\ndocker compose up -d\n./test_api_endpoints.sh\n```\n\n### Project Structure\n\n```\npatchpulse/\n├── app/                    # Application code\n│   ├── backend/           # FastAPI backend service\n│   │   ├── main.py        # Main application entry point\n│   │   ├── models.py      # Pydantic models and SQLAlchemy ORM\n│   │   ├── database.py    # Database connection and setup\n│   │   ├── policy_engine.py # Policy evaluation and guardrails\n│   │   ├── ai_analyzer.py # AI-powered risk analysis (BYO LLM!)\n│   │   ├── ai_features.py # Advanced AI features\n│   │   ├── auth.py        # Authentication system\n│   │   └── requirements.txt\n│   ├── agent/             # Kubernetes agent (Go)\n│   │   ├── cmd/agent/     # Agent main application\n│   │   └── Dockerfile\n│   ├── integrations/     # External integrations\n│   │   ├── git/           # GitHub/GitLab integration\n│   │   ├── slack/         # Slack notifications\n│   │   ├── teams/         # Microsoft Teams integration\n│   │   ├── pagerduty/     # PagerDuty integration\n│   │   └── email/         # Email notifications\n│   └── ui/                # Dashboard UI (served at /dashboard)\n├── docs/                  # Technical documentation\n├── helm/                  # Kubernetes Helm charts\n├── docker-compose.yml     # Local development setup\n└── README.md             # This file\n```\n\n---\n\n## 💼 Use Cases\n\n### 1. CI/CD Pipeline Integration\n\nIntegrate PatchPulse into your CI/CD pipeline to automatically analyze PRs:\n\n```yaml\n# GitHub Actions example\n- name: Analyze with PatchPulse\n  run: |\n    curl -X POST $PATCHPULSE_URL/api/v1/change-events \\\n      -H \"Content-Type: application/json\" \\\n      -d @change-event.json\n```\n\n### 2. Pre-Deployment Validation\n\nValidate Kubernetes manifests before deployment:\n\n```bash\n# Analyze deployment manifests\nkubectl apply --dry-run=client -f deployment.yaml | \\\n  patchpulse analyze --source=manual\n```\n\n### 3. Compliance Auditing\n\nTrack compliance with Kubernetes best practices:\n\n```bash\n# Get compliance report\ncurl http://localhost:8000/api/v1/analytics/compliance\n```\n\n### 4. Incident Prevention\n\nPrevent production incidents by catching risky changes:\n\n- Missing resource limits\n- Security misconfigurations\n- Image tag issues\n- Network policy violations\n\n### 5. Team Education\n\nUse PatchPulse to educate teams on Kubernetes best practices:\n\n- Real-time feedback on PRs\n- Detailed explanations of guardrail violations\n- Historical analytics on common mistakes\n\n---\n\n## 🛡️ Security\n\n- **API keys never exposed** in logs or responses\n- **Least-privilege RBAC** for agent\n- **Encrypted database** connections\n- **TLS** for all API communications\n- **Audit logging** for all decisions\n- **Rate limiting** on API endpoints\n- **Self-hosted** - your data stays on your infrastructure\n\nSee [SECURITY.md](SECURITY.md) for detailed security information.\n\n---\n\n## 🤝 Contributing\n\nWe welcome contributions! PatchPulse is 100% open source and community-driven.\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n### Areas for Contribution\n\n- 🐛 Bug fixes\n- ✨ New features\n- 📚 Documentation improvements\n- 🧪 Test coverage\n- 🌐 Translations\n- 🎨 UI/UX improvements\n- 🔌 New integrations\n\n---\n\n## 📄 License\n\nThis project is licensed under the **PatchPulse Non-Commercial License** - see the [LICENSE](LICENSE) file for details.\n\n**✅ Permitted Uses:**\n- Personal use\n- Educational use\n- Research and development\n- Internal use within non-profit organizations\n- Contributing to the PatchPulse project\n- Forking and modifying for personal/educational purposes\n\n**❌ Prohibited Uses:**\n- Commercial use (selling, licensing, or providing as a service)\n- Use in commercial products or services\n- Reselling or redistributing for profit\n- Use by for-profit companies without explicit written permission\n\n**💼 Commercial Licensing:**\nFor commercial use, please contact us to obtain a commercial license. Commercial licenses are available for:\n- SaaS providers\n- Enterprise deployments\n- Commercial products incorporating PatchPulse\n- Consulting services using PatchPulse\n\n**Contact:** amarkdotdev@gmail.com\n\nThis license protects the open-source nature of PatchPulse while ensuring commercial use requires proper licensing.\n\n---\n\n## 🆘 Support\n\n### Getting Help\n\n- **Documentation**: http://localhost:8000/docs (when running locally)\n- **Website**: https://patchpulse.dev\n- **Issues**: https://github.com/amarkdotdev/patchpulse/issues\n- **Discussions**: https://github.com/amarkdotdev/patchpulse/discussions\n- **Email**: amarkdotdev@gmail.com\n\n### Community\n\n- ⭐ Star us on GitHub if you find PatchPulse useful!\n- 🐛 Report bugs via GitHub Issues\n- 💡 Suggest features via GitHub Discussions\n- 📖 Improve documentation via Pull Requests\n\n---\n\n## ☕ Support the Project\n\nIf PatchPulse has been helpful to you, consider supporting the project:\n\n**[☕ Buy Me a Coffee](https://buymeacoffee.com/aaronmark)**\n\nYour support helps maintain and improve PatchPulse. Thank you! 🙏\n\n---\n\n## 🎯 Roadmap\n\n- [ ] Multi-tenant support (in progress)\n- [ ] Custom guardrail DSL\n- [ ] Integration with more Git providers (Bitbucket, Azure DevOps)\n- [ ] Additional AI provider support\n- [ ] Compliance reporting (SOC2, ISO27001)\n- [ ] Enhanced documentation\n- [ ] Local LLM support (Ollama, LocalAI)\n- [ ] Webhook support for real-time PR analysis\n- [ ] Custom risk scoring algorithms\n- [ ] Policy templates library\n\n---\n\n## 👨‍💻 About the Creator\n\nPatchPulse was created by **Aaron Mark**, a passionate DevOps engineer from **Israel** 🇮🇱. \n\nAfter experiencing countless production incidents that could have been prevented, Aaron built PatchPulse to help engineering teams ship with confidence. Israel is Aaron's home, and it's from this innovative tech ecosystem that PatchPulse was born.\n\nThe project reflects the values of the Israeli tech community: innovation, pragmatism, and a focus on solving real problems that engineers face every day.\n\n**Connect with Aaron:**\n- 📧 Email: amarkdotdev@gmail.com\n- 🐙 GitHub: [@amarkdotdev](https://github.com/amarkdotdev)\n- ☕ Buy Me a Coffee: [buymeacoffee.com/aaronmark](https://buymeacoffee.com/aaronmark)\n\n---\n\n## 🙏 Acknowledgments\n\nBuilt with ❤️ by the open source community. Special thanks to all contributors!\n\n### Technologies Used\n\n- **FastAPI** - Modern Python web framework\n- **PostgreSQL** - Robust relational database\n- **Go** - High-performance Kubernetes agent\n- **React/Vue** - Dashboard UI (if applicable)\n- **Docker** - Containerization\n- **Kubernetes** - Container orchestration\n\n---\n\n<div align=\"center\">\n\n**🔓 Open Source | 🤖 Bring Your Own LLM | 🚀 Self-Hosted**\n\n**Made with ❤️ in Israel for the Kubernetes community worldwide**\n\n[⭐ Star on GitHub](https://github.com/amarkdotdev/patchpulse) • [📖 Documentation](https://patchpulse.dev) • [☕ Buy Me a Coffee](https://buymeacoffee.com/aaronmark) • [🐛 Report Bug](https://github.com/amarkdotdev/patchpulse/issues)\n\n</div>\n"}, "ebe01434a968c9fd45b70628cb778a369f15d7ae": {"t": 1785764236.2593799, "n": 16067, "h": "27494c995d4a433b", "c": "# PatchPulse\n\n**🔓 100% Open Source | 🤖 Bring Your Own LLM | 🚀 Self-Hosted Kubernetes Risk Analysis**\n\nPatchPulse is a self-hosted, open-source solution that prevents production incidents by analyzing infrastructure changes and cluster signals before deployment. It combines rule-based guardrails with AI-powered analysis to provide explainable risk scores and automated enforcement.\n\n## ✨ Key Features\n\n- **🔓 Fully Open Source** - Non-commercial license, no vendor lock-in\n- **🤖 Bring Your Own LLM** - Use OpenAI, DeepSeek, Claude, Gemini, or any OpenAI-compatible API\n- **🏠 Self-Hosted** - Your data stays on your infrastructure\n- **🛡️ 11+ Guardrails** - Rule-based checks for Kubernetes best practices\n- **🧠 AI-Powered Analysis** - Security scanning, recommendations, incident prediction\n- **⚡ Real-Time** - WebSocket updates and instant notifications\n- **🔌 Integrations** - GitHub, GitLab, Slack, Teams, PagerDuty, Email\n- **📊 Enterprise Features** - Admission webhooks, policy bundles, SBOM verification, multi-tenancy\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Docker (running)\n- Python 3.11+ (for local development)\n- Go 1.21+ (for agent development)\n- kubectl (for Kubernetes integration)\n\n### 1. Clone the Repository\n\n```bash\ngit clone https://github.com/amarkdotdev/patchpulse.git\ncd patchpulse\n```\n\n### 2. Configure Your LLM Provider\n\nPatchPulse supports multiple AI providers. **You only need to provide an API key for ONE provider:**\n\n```bash\n# Create .env file\ntouch .env\n\n# Option 1: OpenAI (recommended for best results)\necho \"OPENAI_API_KEY=sk-your-key-here\" >> .env\n\n# Option 2: DeepSeek (cost-effective alternative)\n# echo \"DEEPSEEK_API_KEY=sk-your-key-here\" >> .env\n\n# Option 3: Claude (Anthropic)\n# echo \"ANTHROPIC_API_KEY=sk-ant-your-key-here\" >> .env\n# Note: Requires: pip install anthropic\n\n# Option 4: Google Gemini\n# echo \"GEMINI_API_KEY=your-key-here\" >> .env\n# Note: Requires: pip install google-generativeai\n\n# Optionally specify which provider to use (defaults to first available)\n# echo \"AI_PROVIDER=openai\" >> .env\n```\n\n**💡 No LLM? No Problem!** PatchPulse works without AI - you'll get rule-based guardrails and risk scoring. AI features will be disabled gracefully.\n\n### 3. Start PatchPulse\n\n```bash\n# Start all services\ndocker compose up -d\n\n# Check logs\ndocker compose logs -f backend\n\n# Wait for services to be ready (about 10-15 seconds)\n```\n\n### 4. Access the Application\n\nOnce PatchPulse is running, access it at:\n\n- **Dashboard**: http://localhost:8000/dashboard\n  - Main user interface for monitoring decisions, viewing analytics, and managing configurations\n  - Real-time updates via WebSocket\n  - Risk visualization and decision history\n\n- **API Documentation**: http://localhost:8000/docs\n  - Interactive Swagger/OpenAPI documentation\n  - Test API endpoints directly from the browser\n  - Full API reference\n\n- **Health Check**: http://localhost:8000/health\n  - Service health status\n  - Database connectivity check\n\n- **API Root**: http://localhost:8000/api\n  - API information and available endpoints\n\n### 5. Start Using PatchPulse\n\n1. **Access the Dashboard**: Open http://localhost:8000/dashboard in your browser\n2. **View Decisions**: See real-time risk analysis and decisions\n3. **Configure Integrations**: Set up GitHub, GitLab, Slack, or other integrations via the API\n4. **Monitor Analytics**: Track risk trends, blocked changes, and system health\n\n**Note**: The dashboard is the main interface for PatchPulse. The website (patchpulse.dev) is a separate marketing site and not part of this repository.\n\n## 📖 Table of Contents\n\n- [Architecture](#-architecture)\n- [Configuration](#-configuration)\n- [LLM Provider Setup](#-llm-provider-setup)\n- [API Usage](#-api-usage)\n- [Deployment](#-deployment)\n- [Development](#-development)\n- [Contributing](#-contributing)\n- [License](#-license)\n\n## 🏗️ Architecture\n\n### Components\n\n1. **Backend (FastAPI)**\n   - REST API for change events and decisions\n   - Policy engine with 11+ guardrails\n   - AI-powered risk analysis (bring your own LLM!)\n   - PostgreSQL database for persistence\n   - WebSocket support for real-time updates\n\n2. **Agent (Go)**\n   - Kubernetes cluster monitoring\n   - Resource snapshotting\n   - Event watching\n   - Least-privilege RBAC\n\n3. **Git Integrations**\n   - GitHub PR analysis\n   - GitLab MR analysis\n   - Diff parsing and manifest extraction\n\n4. **Notification Integrations**\n   - Slack notifications with interactive approval buttons\n   - Email notifications\n   - Microsoft Teams integration\n   - PagerDuty integration\n\n5. **Dashboard UI** (Primary Interface)\n   - Real-time decision monitoring via WebSocket\n   - Risk visualization and analytics\n   - Decision history and filtering\n   - Export functionality (CSV/JSON)\n   - Accessible at `/dashboard` endpoint\n\n### Data Flow\n\n```\n1. Developer creates PR/MR → Git integration detects change\n2. Change event sent to backend → Policy engine evaluates\n3. AI analysis runs (if configured) → Security scan, recommendations, predictions\n4. Risk score calculated (0-100) → Decision made (allow/block)\n5. Notification sent to Slack/Teams → Decision stored in database\n6. Dashboard updates in real-time via WebSocket\n```\n\n## 🔧 Configuration\n\n### Environment Variables\n\nCreate a `.env` file in the root directory:\n\n```bash\n# Database\nDATABASE_URL=postgresql://patchpulse:patchpulse@postgres:5432/patchpulse\n\n# Policy Mode (advisory or enforce)\nPOLICY_MODE=advisory\n\n# Logging\nLOG_LEVEL=INFO\n\n# AI Provider - Choose ONE (see LLM Provider Setup section)\nOPENAI_API_KEY=your_openai_api_key\n# OR\n# DEEPSEEK_API_KEY=your_deepseek_api_key\n# OR\n# ANTHROPIC_API_KEY=your_anthropic_api_key\n# OR\n# GEMINI_API_KEY=your_gemini_api_key\n\n# Optional: Specify which provider to use (defaults to first available)\nAI_PROVIDER=openai\n\n# Git Integration\nGITHUB_TOKEN=your_github_token\nGITHUB_REPOS=owner/repo1,owner/repo2\nGITLAB_TOKEN=your_gitlab_token\nGITLAB_PROJECTS=12345,67890\n\n# JWT Secret (auto-generated if not set)\nJWT_SECRET_KEY=your_jwt_secret\n```\n\n### Policy Modes\n\n- **`advisory`**: Logs decisions but doesn't block changes (default)\n- **`enforce`**: Blocks high-risk changes (score ≥ 70)\n\n## 🤖 LLM Provider Setup\n\nPatchPulse is **100% open source** and supports **bring your own LLM**. You can use any of these providers:\n\n### Supported Providers\n\n| Provider | Cost | Quality | Setup |\n|----------|------|---------|-------|\n| **OpenAI** | $$$ | ⭐⭐⭐⭐⭐ | `OPENAI_API_KEY=sk-...` |\n| **DeepSeek** | $ | ⭐⭐⭐⭐ | `DEEPSEEK_API_KEY=sk-...` |\n| **Claude** | $$$ | ⭐⭐⭐⭐⭐ | `ANTHROPIC_API_KEY=sk-ant-...` |\n| **Gemini** | $$ | ⭐⭐⭐⭐ | `GEMINI_API_KEY=...` |\n\n### OpenAI\n\n```bash\nexport OPENAI_API_KEY=sk-your-key-here\n# Or in .env file:\necho \"OPENAI_API_KEY=sk-your-key-here\" >> .env\n```\n\n**Models**: Uses `gpt-4o-mini` by default (cost-effective). You can modify `ai_analyzer.py` to use other models.\n\n### DeepSeek (Recommended for Cost-Conscious Users)\n\n```bash\nexport DEEPSEEK_API_KEY=sk-your-key-here\n# Or in .env file:\necho \"DEEPSEEK_API_KEY=sk-your-key-here\" >> .env\n```\n\n**Models**: Uses `deepseek-chat` by default. OpenAI-compatible API.\n\n### Claude (Anthropic)\n\n```bash\n# First install the package\npip install anthropic\n\nexport ANTHROPIC_API_KEY=sk-ant-your-key-here\n# Or in .env file:\necho \"ANTHROPIC_API_KEY=sk-ant-your-key-here\" >> .env\n```\n\n**Models**: Uses `claude-3-5-sonnet-20241022` by default.\n\n### Google Gemini\n\n```bash\n# First install the package\npip install google-generativeai\n\nexport GEMINI_API_KEY=your-key-here\n# Or in .env file:\necho \"GEMINI_API_KEY=your-key-here\" >> .env\n```\n\n**Models**: Uses `gemini-1.5-pro` by default.\n\n### Using a Custom OpenAI-Compatible API\n\nPatchPulse supports any OpenAI-compatible API endpoint (Ollama, LocalAI, vLLM, etc.):\n\n```bash\n# Set a dummy API key (not used for local endpoints)\nexport OPENAI_API_KEY=not-used\n\n# Set your custom endpoint\nexport OPENAI_BASE_URL=http://localhost:11434/v1  # Ollama example\n# Or\nexport OPENAI_BASE_URL=http://localhost:8080/v1   # LocalAI example\n\n# Or in .env file:\necho \"OPENAI_API_KEY=not-used\" >> .env\necho \"OPENAI_BASE_URL=http://localhost:11434/v1\" >> .env\n```\n\n**Examples:**\n- **Ollama**: `OPENAI_BASE_URL=http://localhost:11434/v1`\n- **LocalAI**: `OPENAI_BASE_URL=http://localhost:8080/v1`\n- **vLLM**: `OPENAI_BASE_URL=http://localhost:8000/v1`\n- **Any OpenAI-compatible service**: Just set the base URL!\n\nThe system will automatically use your custom endpoint with the OpenAI client.\n\n### No LLM Required\n\n**PatchPulse works perfectly without any LLM!** If no API key is provided:\n- ✅ All rule-based guardrails work\n- ✅ Risk scoring works\n- ✅ All integrations work\n- ✅ Dashboard works\n- ⚠️ AI-powered features are disabled (security scanning, recommendations, predictions)\n\n## 📊 API Usage\n\n### Create Change Event\n\n```bash\ncurl -X POST http://localhost:8000/api/v1/change-events \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"source\": \"github\",\n    \"repo\": \"org/repo\",\n    \"sha\": \"abc123\",\n    \"pr_number\": 42,\n    \"branch\": \"feature-branch\",\n    \"files\": [\"k8s/deployment.yaml\"],\n    \"diff_hunks\": [{\n      \"file\": \"k8s/deployment.yaml\",\n      \"hunk\": \"- limits:\\n  cpu: 500m\"\n    }],\n    \"timestamp\": \"2026-01-01T00:00:00Z\"\n  }'\n```\n\n### Get Decisions\n\n```bash\ncurl http://localhost:8000/api/v1/decisions?limit=10\n```\n\n### Get Analytics\n\n```bash\ncurl http://localhost:8000/api/v1/analytics/summary\n```\n\nSee `/docs` for interactive API documentation.\n\n## 🚢 Deployment\n\n### Docker Compose (Recommended for Quick Start)\n\n```bash\ndocker compose up -d\n```\n\n### Kubernetes (Helm)\n\n**Option 1: Using your `.env` file (Recommended)**\n\n```bash\n# Create a values file from your .env\n# This reads your .env file and creates Helm values\ncat > /tmp/patchpulse-values.yaml <<EOF\nenv:\n  DATABASE_URL: \"postgresql://patchpulse:patchpulse@postgres:5432/patchpulse\"\n  POLICY_MODE: \"advisory\"\n  LOG_LEVEL: \"INFO\"\n  OPENAI_API_KEY: \"$(grep OPENAI_API_KEY .env | cut -d '=' -f2)\"\n  DEEPSEEK_API_KEY: \"$(grep DEEPSEEK_API_KEY .env | cut -d '=' -f2 || echo '')\"\n  ANTHROPIC_API_KEY: \"$(grep ANTHROPIC_API_KEY .env | cut -d '=' -f2 || echo '')\"\n  GEMINI_API_KEY: \"$(grep GEMINI_API_KEY .env | cut -d '=' -f2 || echo '')\"\nEOF\n\n# Install backend using values from .env\nhelm install patchpulse-backend ./helm/backend \\\n  --namespace patchpulse \\\n  --create-namespace \\\n  --values /tmp/patchpulse-values.yaml\n\n# Install agent\nhelm install patchpulse-agent ./helm/agent \\\n  --namespace patchpulse \\\n  --set env.BACKEND_URL=http://patchpulse-backend:8000\n```\n\n**Option 2: Using --set-file (Alternative)**\n\n```bash\n# Install backend with API key from .env file\nhelm install patchpulse-backend ./helm/backend \\\n  --namespace patchpulse \\\n  --create-namespace \\\n  --set env.OPENAI_API_KEY=\"$(grep OPENAI_API_KEY .env | cut -d '=' -f2)\" \\\n  --set env.POLICY_MODE=advisory\n\n# Install agent\nhelm install patchpulse-agent ./helm/agent \\\n  --namespace patchpulse \\\n  --set env.BACKEND_URL=http://patchpulse-backend:8000\n```\n\n**Option 3: Manual values override**\n\nEdit `helm/backend/values.yaml` and add your API keys to the `env` section, then install:\n\n```bash\nhelm install patchpulse-backend ./helm/backend \\\n  --namespace patchpulse \\\n  --create-namespace\n```\n\n### Production Considerations\n\n- Use environment variables for secrets (never hardcode)\n- Set up proper TLS/SSL certificates\n- Configure database backups\n- Set up monitoring and alerting\n- Use a managed PostgreSQL database for production\n\n## 🛠️ Development\n\n### Local Development Setup\n\n```bash\n# Backend\ncd app/backend\npython -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\npip install -r requirements.txt\nuvicorn main:app --reload\n\n# Agent\ncd app/agent\ngo run cmd/agent/main.go\n\n# Git Integration\ncd app/integrations/git\npython poller.py\n```\n\n### Running Tests\n\n```bash\n# Unit tests\ncd app/backend\npytest tests/\n\n# Integration tests\ndocker compose up -d\n./test_api_endpoints.sh\n```\n\n### Project Structure\n\n```\npatchpulse/\n├── app/                    # Application code\n│   ├── backend/           # FastAPI backend service\n│   │   ├── main.py        # Main application entry point\n│   │   ├── models.py      # Pydantic models and SQLAlchemy ORM\n│   │   ├── database.py    # Database connection and setup\n│   │   ├── policy_engine.py # Policy evaluation and guardrails\n│   │   ├── ai_analyzer.py # AI-powered risk analysis (BYO LLM!)\n│   │   ├── ai_features.py # Advanced AI features\n│   │   ├── auth.py        # Authentication system\n│   │   └── requirements.txt\n│   ├── agent/             # Kubernetes agent (Go)\n│   │   ├── cmd/agent/     # Agent main application\n│   │   └── Dockerfile\n│   ├── integrations/     # External integrations\n│   │   ├── git/           # GitHub/GitLab integration\n│   │   └── slack/         # Slack notifications\n│   └── ui/                # Dashboard UI (served at /dashboard)\n├── docs/                  # Technical documentation\n├── helm/                  # Kubernetes Helm charts\n├── docker-compose.yml     # Local development setup\n└── README.md             # This file\n```\n\n## 🛡️ Security\n\n- **API keys never exposed** in logs or responses\n- **Least-privilege RBAC** for agent\n- **Encrypted database** connections\n- **TLS** for all API communications\n- **Audit logging** for all decisions\n- **Rate limiting** on API endpoints\n- **Self-hosted** - your data stays on your infrastructure\n\nSee [SECURITY.md](SECURITY.md) for detailed security information.\n\n## 🤝 Contributing\n\nWe welcome contributions! PatchPulse is 100% open source and community-driven.\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n## 📄 License\n\nThis project is licensed under the **PatchPulse Non-Commercial License** - see the [LICENSE](LICENSE) file for details.\n\n**✅ Permitted Uses:**\n- Personal use\n- Educational use\n- Research and development\n- Internal use within non-profit organizations\n- Contributing to the PatchPulse project\n- Forking and modifying for personal/educational purposes\n\n**❌ Prohibited Uses:**\n- Commercial use (selling, licensing, or providing as a service)\n- Use in commercial products or services\n- Reselling or redistributing for profit\n- Use by for-profit companies without explicit written permission\n\n**💼 Commercial Licensing:**\nFor commercial use, please contact us to obtain a commercial license. Commercial licenses are available for:\n- SaaS providers\n- Enterprise deployments\n- Commercial products incorporating PatchPulse\n- Consulting services using PatchPulse\n\n**Contact:** licensing@patchpulse.dev\n\nThis license protects the open-source nature of PatchPulse while ensuring commercial use requires proper licensing.\n\n## 🆘 Support\n\n- **Documentation**: http://localhost:8000/docs (when running locally)\n- **Issues**: https://github.com/amarkdotdev/patchpulse/issues\n- **Discussions**: https://github.com/amarkdotdev/patchpulse/discussions\n\n## 🎯 Roadmap\n\n- [ ] Multi-tenant support (in progress)\n- [ ] Custom guardrail DSL\n- [ ] Integration with more Git providers\n- [ ] Additional AI provider support\n- [ ] Compliance reporting\n- [ ] Enhanced documentation\n- [ ] Local LLM support (Ollama, LocalAI)\n\n## 👨‍💻 About the Creator\n\nPatchPulse was created by **Aaron Mark**, a passionate DevOps engineer from **Israel** 🇮🇱. \n\nAfter experiencing countless production incidents that could have been prevented, Aaron built PatchPulse to help engineering teams ship with confidence. Israel is Aaron's home, and it's from this innovative tech ecosystem that PatchPulse was born.\n\nThe project reflects the values of the Israeli tech community: innovation, pragmatism, and a focus on solving real problems that engineers face every day.\n\n## 🙏 Acknowledgments\n\nBuilt with ❤️ by the open source community. Special thanks to all contributors!\n\n---\n\n**🔓 Open Source | 🤖 Bring Your Own LLM | 🚀 Self-Hosted**\n\n**Made with ❤️ in Israel for the Kubernetes community worldwide**\n"}, "04aaced8c3ac3aafd27176304d6a5b270453b8c7": {"t": 1785764237.7137525, "n": 14755, "h": "7c5c185fc2816ab7", "c": "# PatchPulse\n\n**🔓 100% Open Source | 🤖 Bring Your Own LLM | 🚀 Self-Hosted Kubernetes Risk Analysis**\n\nPatchPulse is a self-hosted, open-source solution that prevents production incidents by analyzing infrastructure changes and cluster signals before deployment. It combines rule-based guardrails with AI-powered analysis to provide explainable risk scores and automated enforcement.\n\n## ✨ Key Features\n\n- **🔓 Fully Open Source** - Non-commercial license, no vendor lock-in\n- **🤖 Bring Your Own LLM** - Use OpenAI, DeepSeek, Claude, Gemini, or any OpenAI-compatible API\n- **🏠 Self-Hosted** - Your data stays on your infrastructure\n- **🛡️ 11+ Guardrails** - Rule-based checks for Kubernetes best practices\n- **🧠 AI-Powered Analysis** - Security scanning, recommendations, incident prediction\n- **⚡ Real-Time** - WebSocket updates and instant notifications\n- **🔌 Integrations** - GitHub, GitLab, Slack, Teams, PagerDuty, Email\n- **📊 Enterprise Features** - Admission webhooks, policy bundles, SBOM verification, multi-tenancy\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Docker (running)\n- Python 3.11+ (for local development)\n- Go 1.21+ (for agent development)\n- kubectl (for Kubernetes integration)\n\n### 1. Clone the Repository\n\n```bash\ngit clone https://github.com/amarkdotdev/patchpulse.git\ncd patchpulse\n```\n\n### 2. Configure Your LLM Provider\n\nPatchPulse supports multiple AI providers. **You only need to provide an API key for ONE provider:**\n\n```bash\n# Create .env file\ntouch .env\n\n# Option 1: OpenAI (recommended for best results)\necho \"OPENAI_API_KEY=sk-your-key-here\" >> .env\n\n# Option 2: DeepSeek (cost-effective alternative)\n# echo \"DEEPSEEK_API_KEY=sk-your-key-here\" >> .env\n\n# Option 3: Claude (Anthropic)\n# echo \"ANTHROPIC_API_KEY=sk-ant-your-key-here\" >> .env\n# Note: Requires: pip install anthropic\n\n# Option 4: Google Gemini\n# echo \"GEMINI_API_KEY=your-key-here\" >> .env\n# Note: Requires: pip install google-generativeai\n\n# Optionally specify which provider to use (defaults to first available)\n# echo \"AI_PROVIDER=openai\" >> .env\n```\n\n**💡 No LLM? No Problem!** PatchPulse works without AI - you'll get rule-based guardrails and risk scoring. AI features will be disabled gracefully.\n\n### 3. Start PatchPulse\n\n```bash\n# Start all services\ndocker compose up -d\n\n# Check logs\ndocker compose logs -f backend\n\n# Wait for services to be ready (about 10-15 seconds)\n```\n\n### 4. Access the Application\n\nOnce PatchPulse is running, access it at:\n\n- **Dashboard**: http://localhost:8000/dashboard\n  - Main user interface for monitoring decisions, viewing analytics, and managing configurations\n  - Real-time updates via WebSocket\n  - Risk visualization and decision history\n\n- **API Documentation**: http://localhost:8000/docs\n  - Interactive Swagger/OpenAPI documentation\n  - Test API endpoints directly from the browser\n  - Full API reference\n\n- **Health Check**: http://localhost:8000/health\n  - Service health status\n  - Database connectivity check\n\n- **API Root**: http://localhost:8000/api\n  - API information and available endpoints\n\n### 5. Start Using PatchPulse\n\n1. **Access the Dashboard**: Open http://localhost:8000/dashboard in your browser\n2. **View Decisions**: See real-time risk analysis and decisions\n3. **Configure Integrations**: Set up GitHub, GitLab, Slack, or other integrations via the API\n4. **Monitor Analytics**: Track risk trends, blocked changes, and system health\n\n**Note**: The dashboard is the main interface for PatchPulse. The website (patchpulse.dev) is a separate marketing site and not part of this repository.\n\n## 📖 Table of Contents\n\n- [Architecture](#-architecture)\n- [Configuration](#-configuration)\n- [LLM Provider Setup](#-llm-provider-setup)\n- [API Usage](#-api-usage)\n- [Deployment](#-deployment)\n- [Development](#-development)\n- [Contributing](#-contributing)\n- [License](#-license)\n\n## 🏗️ Architecture\n\n### Components\n\n1. **Backend (FastAPI)**\n   - REST API for change events and decisions\n   - Policy engine with 11+ guardrails\n   - AI-powered risk analysis (bring your own LLM!)\n   - PostgreSQL database for persistence\n   - WebSocket support for real-time updates\n\n2. **Agent (Go)**\n   - Kubernetes cluster monitoring\n   - Resource snapshotting\n   - Event watching\n   - Least-privilege RBAC\n\n3. **Git Integrations**\n   - GitHub PR analysis\n   - GitLab MR analysis\n   - Diff parsing and manifest extraction\n\n4. **Notification Integrations**\n   - Slack notifications with interactive approval buttons\n   - Email notifications\n   - Microsoft Teams integration\n   - PagerDuty integration\n\n5. **Dashboard UI** (Primary Interface)\n   - Real-time decision monitoring via WebSocket\n   - Risk visualization and analytics\n   - Decision history and filtering\n   - Export functionality (CSV/JSON)\n   - Accessible at `/dashboard` endpoint\n\n### Data Flow\n\n```\n1. Developer creates PR/MR → Git integration detects change\n2. Change event sent to backend → Policy engine evaluates\n3. AI analysis runs (if configured) → Security scan, recommendations, predictions\n4. Risk score calculated (0-100) → Decision made (allow/block)\n5. Notification sent to Slack/Teams → Decision stored in database\n6. Dashboard updates in real-time via WebSocket\n```\n\n## 🔧 Configuration\n\n### Environment Variables\n\nCreate a `.env` file in the root directory:\n\n```bash\n# Database\nDATABASE_URL=postgresql://patchpulse:patchpulse@postgres:5432/patchpulse\n\n# Policy Mode (advisory or enforce)\nPOLICY_MODE=advisory\n\n# Logging\nLOG_LEVEL=INFO\n\n# AI Provider - Choose ONE (see LLM Provider Setup section)\nOPENAI_API_KEY=your_openai_api_key\n# OR\n# DEEPSEEK_API_KEY=your_deepseek_api_key\n# OR\n# ANTHROPIC_API_KEY=your_anthropic_api_key\n# OR\n# GEMINI_API_KEY=your_gemini_api_key\n\n# Optional: Specify which provider to use (defaults to first available)\nAI_PROVIDER=openai\n\n# Git Integration\nGITHUB_TOKEN=your_github_token\nGITHUB_REPOS=owner/repo1,owner/repo2\nGITLAB_TOKEN=your_gitlab_token\nGITLAB_PROJECTS=12345,67890\n\n# JWT Secret (auto-generated if not set)\nJWT_SECRET_KEY=your_jwt_secret\n```\n\n### Policy Modes\n\n- **`advisory`**: Logs decisions but doesn't block changes (default)\n- **`enforce`**: Blocks high-risk changes (score ≥ 70)\n\n## 🤖 LLM Provider Setup\n\nPatchPulse is **100% open source** and supports **bring your own LLM**. You can use any of these providers:\n\n### Supported Providers\n\n| Provider | Cost | Quality | Setup |\n|----------|------|---------|-------|\n| **OpenAI** | $$$ | ⭐⭐⭐⭐⭐ | `OPENAI_API_KEY=sk-...` |\n| **DeepSeek** | $ | ⭐⭐⭐⭐ | `DEEPSEEK_API_KEY=sk-...` |\n| **Claude** | $$$ | ⭐⭐⭐⭐⭐ | `ANTHROPIC_API_KEY=sk-ant-...` |\n| **Gemini** | $$ | ⭐⭐⭐⭐ | `GEMINI_API_KEY=...` |\n\n### OpenAI\n\n```bash\nexport OPENAI_API_KEY=sk-your-key-here\n# Or in .env file:\necho \"OPENAI_API_KEY=sk-your-key-here\" >> .env\n```\n\n**Models**: Uses `gpt-4o-mini` by default (cost-effective). You can modify `ai_analyzer.py` to use other models.\n\n### DeepSeek (Recommended for Cost-Conscious Users)\n\n```bash\nexport DEEPSEEK_API_KEY=sk-your-key-here\n# Or in .env file:\necho \"DEEPSEEK_API_KEY=sk-your-key-here\" >> .env\n```\n\n**Models**: Uses `deepseek-chat` by default. OpenAI-compatible API.\n\n### Claude (Anthropic)\n\n```bash\n# First install the package\npip install anthropic\n\nexport ANTHROPIC_API_KEY=sk-ant-your-key-here\n# Or in .env file:\necho \"ANTHROPIC_API_KEY=sk-ant-your-key-here\" >> .env\n```\n\n**Models**: Uses `claude-3-5-sonnet-20241022` by default.\n\n### Google Gemini\n\n```bash\n# First install the package\npip install google-generativeai\n\nexport GEMINI_API_KEY=your-key-here\n# Or in .env file:\necho \"GEMINI_API_KEY=your-key-here\" >> .env\n```\n\n**Models**: Uses `gemini-1.5-pro` by default.\n\n### Using a Custom OpenAI-Compatible API\n\nPatchPulse supports any OpenAI-compatible API endpoint (Ollama, LocalAI, vLLM, etc.):\n\n```bash\n# Set a dummy API key (not used for local endpoints)\nexport OPENAI_API_KEY=not-used\n\n# Set your custom endpoint\nexport OPENAI_BASE_URL=http://localhost:11434/v1  # Ollama example\n# Or\nexport OPENAI_BASE_URL=http://localhost:8080/v1   # LocalAI example\n\n# Or in .env file:\necho \"OPENAI_API_KEY=not-used\" >> .env\necho \"OPENAI_BASE_URL=http://localhost:11434/v1\" >> .env\n```\n\n**Examples:**\n- **Ollama**: `OPENAI_BASE_URL=http://localhost:11434/v1`\n- **LocalAI**: `OPENAI_BASE_URL=http://localhost:8080/v1`\n- **vLLM**: `OPENAI_BASE_URL=http://localhost:8000/v1`\n- **Any OpenAI-compatible service**: Just set the base URL!\n\nThe system will automatically use your custom endpoint with the OpenAI client.\n\n### No LLM Required\n\n**PatchPulse works perfectly without any LLM!** If no API key is provided:\n- ✅ All rule-based guardrails work\n- ✅ Risk scoring works\n- ✅ All integrations work\n- ✅ Dashboard works\n- ⚠️ AI-powered features are disabled (security scanning, recommendations, predictions)\n\n## 📊 API Usage\n\n### Create Change Event\n\n```bash\ncurl -X POST http://localhost:8000/api/v1/change-events \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"source\": \"github\",\n    \"repo\": \"org/repo\",\n    \"sha\": \"abc123\",\n    \"pr_number\": 42,\n    \"branch\": \"feature-branch\",\n    \"files\": [\"k8s/deployment.yaml\"],\n    \"diff_hunks\": [{\n      \"file\": \"k8s/deployment.yaml\",\n      \"hunk\": \"- limits:\\n  cpu: 500m\"\n    }],\n    \"timestamp\": \"2026-01-01T00:00:00Z\"\n  }'\n```\n\n### Get Decisions\n\n```bash\ncurl http://localhost:8000/api/v1/decisions?limit=10\n```\n\n### Get Analytics\n\n```bash\ncurl http://localhost:8000/api/v1/analytics/summary\n```\n\nSee `/docs` for interactive API documentation.\n\n## 🚢 Deployment\n\n### Docker Compose (Recommended for Quick Start)\n\n```bash\ndocker compose up -d\n```\n\n### Kubernetes (Helm)\n\n```bash\n# Install backend\nhelm install patchpulse-backend ./helm/backend \\\n  --namespace patchpulse \\\n  --create-namespace \\\n  --set policy.mode=advisory \\\n  --set ai.openaiApiKey=your_key_here\n\n# Install agent\nhelm install patchpulse-agent ./helm/agent \\\n  --namespace patchpulse \\\n  --set backend.url=http://patchpulse-backend:8000\n```\n\n### Production Considerations\n\n- Use environment variables for secrets (never hardcode)\n- Set up proper TLS/SSL certificates\n- Configure database backups\n- Set up monitoring and alerting\n- Use a managed PostgreSQL database for production\n\n## 🛠️ Development\n\n### Local Development Setup\n\n```bash\n# Backend\ncd app/backend\npython -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\npip install -r requirements.txt\nuvicorn main:app --reload\n\n# Agent\ncd app/agent\ngo run cmd/agent/main.go\n\n# Git Integration\ncd app/integrations/git\npython poller.py\n```\n\n### Running Tests\n\n```bash\n# Unit tests\ncd app/backend\npytest tests/\n\n# Integration tests\ndocker compose up -d\n./test_api_endpoints.sh\n```\n\n### Project Structure\n\n```\npatchpulse/\n├── app/                    # Application code\n│   ├── backend/           # FastAPI backend service\n│   │   ├── main.py        # Main application entry point\n│   │   ├── models.py      # Pydantic models and SQLAlchemy ORM\n│   │   ├── database.py    # Database connection and setup\n│   │   ├── policy_engine.py # Policy evaluation and guardrails\n│   │   ├── ai_analyzer.py # AI-powered risk analysis (BYO LLM!)\n│   │   ├── ai_features.py # Advanced AI features\n│   │   ├── auth.py        # Authentication system\n│   │   └── requirements.txt\n│   ├── agent/             # Kubernetes agent (Go)\n│   │   ├── cmd/agent/     # Agent main application\n│   │   └── Dockerfile\n│   ├── integrations/     # External integrations\n│   │   ├── git/           # GitHub/GitLab integration\n│   │   └── slack/         # Slack notifications\n│   └── ui/                # Dashboard UI (served at /dashboard)\n├── docs/                  # Technical documentation\n├── helm/                  # Kubernetes Helm charts\n├── docker-compose.yml     # Local development setup\n└── README.md             # This file\n```\n\n## 🛡️ Security\n\n- **API keys never exposed** in logs or responses\n- **Least-privilege RBAC** for agent\n- **Encrypted database** connections\n- **TLS** for all API communications\n- **Audit logging** for all decisions\n- **Rate limiting** on API endpoints\n- **Self-hosted** - your data stays on your infrastructure\n\nSee [SECURITY.md](SECURITY.md) for detailed security information.\n\n## 🤝 Contributing\n\nWe welcome contributions! PatchPulse is 100% open source and community-driven.\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n## 📄 License\n\nThis project is licensed under the **PatchPulse Non-Commercial License** - see the [LICENSE](LICENSE) file for details.\n\n**✅ Permitted Uses:**\n- Personal use\n- Educational use\n- Research and development\n- Internal use within non-profit organizations\n- Contributing to the PatchPulse project\n- Forking and modifying for personal/educational purposes\n\n**❌ Prohibited Uses:**\n- Commercial use (selling, licensing, or providing as a service)\n- Use in commercial products or services\n- Reselling or redistributing for profit\n- Use by for-profit companies without explicit written permission\n\n**💼 Commercial Licensing:**\nFor commercial use, please contact us to obtain a commercial license. Commercial licenses are available for:\n- SaaS providers\n- Enterprise deployments\n- Commercial products incorporating PatchPulse\n- Consulting services using PatchPulse\n\n**Contact:** licensing@patchpulse.dev\n\nThis license protects the open-source nature of PatchPulse while ensuring commercial use requires proper licensing.\n\n## 🆘 Support\n\n- **Documentation**: http://localhost:8000/docs (when running locally)\n- **Issues**: https://github.com/amarkdotdev/patchpulse/issues\n- **Discussions**: https://github.com/amarkdotdev/patchpulse/discussions\n\n## 🎯 Roadmap\n\n- [ ] Multi-tenant support (in progress)\n- [ ] Custom guardrail DSL\n- [ ] Integration with more Git providers\n- [ ] Additional AI provider support\n- [ ] Compliance reporting\n- [ ] Enhanced documentation\n- [ ] Local LLM support (Ollama, LocalAI)\n\n## 👨‍💻 About the Creator\n\nPatchPulse was created by **Aaron Mark**, a passionate DevOps engineer from **Israel** 🇮🇱. \n\nAfter experiencing countless production incidents that could have been prevented, Aaron built PatchPulse to help engineering teams ship with confidence. Israel is Aaron's home, and it's from this innovative tech ecosystem that PatchPulse was born.\n\nThe project reflects the values of the Israeli tech community: innovation, pragmatism, and a focus on solving real problems that engineers face every day.\n\n## 🙏 Acknowledgments\n\nBuilt with ❤️ by the open source community. Special thanks to all contributors!\n\n---\n\n**🔓 Open Source | 🤖 Bring Your Own LLM | 🚀 Self-Hosted**\n\n**Made with ❤️ in Israel for the Kubernetes community worldwide**\n"}, "9dfcbc90d0e37d208550019f8a07b981df550747": {"t": 1785764239.216869, "n": 14625, "h": "b74f875f3feb8b64", "c": "# PatchPulse\n\n**🔓 100% Open Source | 🤖 Bring Your Own LLM | 🚀 Self-Hosted Kubernetes Risk Analysis**\n\nPatchPulse is a self-hosted, open-source solution that prevents production incidents by analyzing infrastructure changes and cluster signals before deployment. It combines rule-based guardrails with AI-powered analysis to provide explainable risk scores and automated enforcement.\n\n## ✨ Key Features\n\n- **🔓 Fully Open Source** - Non-commercial license, no vendor lock-in\n- **🤖 Bring Your Own LLM** - Use OpenAI, DeepSeek, Claude, Gemini, or any OpenAI-compatible API\n- **🏠 Self-Hosted** - Your data stays on your infrastructure\n- **🛡️ 11+ Guardrails** - Rule-based checks for Kubernetes best practices\n- **🧠 AI-Powered Analysis** - Security scanning, recommendations, incident prediction\n- **⚡ Real-Time** - WebSocket updates and instant notifications\n- **🔌 Integrations** - GitHub, GitLab, Slack, Teams, PagerDuty, Email\n- **📊 Enterprise Features** - Admission webhooks, policy bundles, SBOM verification, multi-tenancy\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Docker (running)\n- Python 3.11+ (for local development)\n- Go 1.21+ (for agent development)\n- kubectl (for Kubernetes integration)\n\n### 1. Clone the Repository\n\n```bash\ngit clone https://github.com/amarkdotdev/patchpulse.git\ncd patchpulse\n```\n\n### 2. Configure Your LLM Provider\n\nPatchPulse supports multiple AI providers. **You only need to provide an API key for ONE provider:**\n\n```bash\n# Create .env file\ntouch .env\n\n# Option 1: OpenAI (recommended for best results)\necho \"OPENAI_API_KEY=sk-your-key-here\" >> .env\n\n# Option 2: DeepSeek (cost-effective alternative)\n# echo \"DEEPSEEK_API_KEY=sk-your-key-here\" >> .env\n\n# Option 3: Claude (Anthropic)\n# echo \"ANTHROPIC_API_KEY=sk-ant-your-key-here\" >> .env\n# Note: Requires: pip install anthropic\n\n# Option 4: Google Gemini\n# echo \"GEMINI_API_KEY=your-key-here\" >> .env\n# Note: Requires: pip install google-generativeai\n\n# Optionally specify which provider to use (defaults to first available)\n# echo \"AI_PROVIDER=openai\" >> .env\n```\n\n**💡 No LLM? No Problem!** PatchPulse works without AI - you'll get rule-based guardrails and risk scoring. AI features will be disabled gracefully.\n\n### 3. Start PatchPulse\n\n```bash\n# Start all services\ndocker compose up -d\n\n# Check logs\ndocker compose logs -f backend\n\n# Wait for services to be ready (about 10-15 seconds)\n```\n\n### 4. Access the Application\n\nOnce PatchPulse is running, access it at:\n\n- **Dashboard**: http://localhost:8000/dashboard\n  - Main user interface for monitoring decisions, viewing analytics, and managing configurations\n  - Real-time updates via WebSocket\n  - Risk visualization and decision history\n\n- **API Documentation**: http://localhost:8000/docs\n  - Interactive Swagger/OpenAPI documentation\n  - Test API endpoints directly from the browser\n  - Full API reference\n\n- **Health Check**: http://localhost:8000/health\n  - Service health status\n  - Database connectivity check\n\n- **API Root**: http://localhost:8000/api\n  - API information and available endpoints\n\n### 5. Start Using PatchPulse\n\n1. **Access the Dashboard**: Open http://localhost:8000/dashboard in your browser\n2. **View Decisions**: See real-time risk analysis and decisions\n3. **Configure Integrations**: Set up GitHub, GitLab, Slack, or other integrations via the API\n4. **Monitor Analytics**: Track risk trends, blocked changes, and system health\n\n**Note**: The dashboard is the main interface for PatchPulse. The website (patchpulse.dev) is a separate marketing site and not part of this repository.\n\n## 📖 Table of Contents\n\n- [Architecture](#-architecture)\n- [Configuration](#-configuration)\n- [LLM Provider Setup](#-llm-provider-setup)\n- [API Usage](#-api-usage)\n- [Deployment](#-deployment)\n- [Development](#-development)\n- [Contributing](#-contributing)\n- [License](#-license)\n\n## 🏗️ Architecture\n\n### Components\n\n1. **Backend (FastAPI)**\n   - REST API for change events and decisions\n   - Policy engine with 11+ guardrails\n   - AI-powered risk analysis (bring your own LLM!)\n   - PostgreSQL database for persistence\n   - WebSocket support for real-time updates\n\n2. **Agent (Go)**\n   - Kubernetes cluster monitoring\n   - Resource snapshotting\n   - Event watching\n   - Least-privilege RBAC\n\n3. **Git Integrations**\n   - GitHub PR analysis\n   - GitLab MR analysis\n   - Diff parsing and manifest extraction\n\n4. **Notification Integrations**\n   - Slack notifications with interactive approval buttons\n   - Email notifications\n   - Microsoft Teams integration\n   - PagerDuty integration\n\n5. **Dashboard UI**\n   - Real-time decision monitoring\n   - Risk visualization\n   - Analytics and reporting\n   - Export functionality\n\n### Data Flow\n\n```\n1. Developer creates PR/MR → Git integration detects change\n2. Change event sent to backend → Policy engine evaluates\n3. AI analysis runs (if configured) → Security scan, recommendations, predictions\n4. Risk score calculated (0-100) → Decision made (allow/block)\n5. Notification sent to Slack/Teams → Decision stored in database\n6. Dashboard updates in real-time via WebSocket\n```\n\n## 🔧 Configuration\n\n### Environment Variables\n\nCreate a `.env` file in the root directory:\n\n```bash\n# Database\nDATABASE_URL=postgresql://patchpulse:patchpulse@postgres:5432/patchpulse\n\n# Policy Mode (advisory or enforce)\nPOLICY_MODE=advisory\n\n# Logging\nLOG_LEVEL=INFO\n\n# AI Provider - Choose ONE (see LLM Provider Setup section)\nOPENAI_API_KEY=your_openai_api_key\n# OR\n# DEEPSEEK_API_KEY=your_deepseek_api_key\n# OR\n# ANTHROPIC_API_KEY=your_anthropic_api_key\n# OR\n# GEMINI_API_KEY=your_gemini_api_key\n\n# Optional: Specify which provider to use (defaults to first available)\nAI_PROVIDER=openai\n\n# Git Integration\nGITHUB_TOKEN=your_github_token\nGITHUB_REPOS=owner/repo1,owner/repo2\nGITLAB_TOKEN=your_gitlab_token\nGITLAB_PROJECTS=12345,67890\n\n# JWT Secret (auto-generated if not set)\nJWT_SECRET_KEY=your_jwt_secret\n```\n\n### Policy Modes\n\n- **`advisory`**: Logs decisions but doesn't block changes (default)\n- **`enforce`**: Blocks high-risk changes (score ≥ 70)\n\n## 🤖 LLM Provider Setup\n\nPatchPulse is **100% open source** and supports **bring your own LLM**. You can use any of these providers:\n\n### Supported Providers\n\n| Provider | Cost | Quality | Setup |\n|----------|------|---------|-------|\n| **OpenAI** | $$$ | ⭐⭐⭐⭐⭐ | `OPENAI_API_KEY=sk-...` |\n| **DeepSeek** | $ | ⭐⭐⭐⭐ | `DEEPSEEK_API_KEY=sk-...` |\n| **Claude** | $$$ | ⭐⭐⭐⭐⭐ | `ANTHROPIC_API_KEY=sk-ant-...` |\n| **Gemini** | $$ | ⭐⭐⭐⭐ | `GEMINI_API_KEY=...` |\n\n### OpenAI\n\n```bash\nexport OPENAI_API_KEY=sk-your-key-here\n# Or in .env file:\necho \"OPENAI_API_KEY=sk-your-key-here\" >> .env\n```\n\n**Models**: Uses `gpt-4o-mini` by default (cost-effective). You can modify `ai_analyzer.py` to use other models.\n\n### DeepSeek (Recommended for Cost-Conscious Users)\n\n```bash\nexport DEEPSEEK_API_KEY=sk-your-key-here\n# Or in .env file:\necho \"DEEPSEEK_API_KEY=sk-your-key-here\" >> .env\n```\n\n**Models**: Uses `deepseek-chat` by default. OpenAI-compatible API.\n\n### Claude (Anthropic)\n\n```bash\n# First install the package\npip install anthropic\n\nexport ANTHROPIC_API_KEY=sk-ant-your-key-here\n# Or in .env file:\necho \"ANTHROPIC_API_KEY=sk-ant-your-key-here\" >> .env\n```\n\n**Models**: Uses `claude-3-5-sonnet-20241022` by default.\n\n### Google Gemini\n\n```bash\n# First install the package\npip install google-generativeai\n\nexport GEMINI_API_KEY=your-key-here\n# Or in .env file:\necho \"GEMINI_API_KEY=your-key-here\" >> .env\n```\n\n**Models**: Uses `gemini-1.5-pro` by default.\n\n### Using a Custom OpenAI-Compatible API\n\nPatchPulse supports any OpenAI-compatible API endpoint (Ollama, LocalAI, vLLM, etc.):\n\n```bash\n# Set a dummy API key (not used for local endpoints)\nexport OPENAI_API_KEY=not-used\n\n# Set your custom endpoint\nexport OPENAI_BASE_URL=http://localhost:11434/v1  # Ollama example\n# Or\nexport OPENAI_BASE_URL=http://localhost:8080/v1   # LocalAI example\n\n# Or in .env file:\necho \"OPENAI_API_KEY=not-used\" >> .env\necho \"OPENAI_BASE_URL=http://localhost:11434/v1\" >> .env\n```\n\n**Examples:**\n- **Ollama**: `OPENAI_BASE_URL=http://localhost:11434/v1`\n- **LocalAI**: `OPENAI_BASE_URL=http://localhost:8080/v1`\n- **vLLM**: `OPENAI_BASE_URL=http://localhost:8000/v1`\n- **Any OpenAI-compatible service**: Just set the base URL!\n\nThe system will automatically use your custom endpoint with the OpenAI client.\n\n### No LLM Required\n\n**PatchPulse works perfectly without any LLM!** If no API key is provided:\n- ✅ All rule-based guardrails work\n- ✅ Risk scoring works\n- ✅ All integrations work\n- ✅ Dashboard works\n- ⚠️ AI-powered features are disabled (security scanning, recommendations, predictions)\n\n## 📊 API Usage\n\n### Create Change Event\n\n```bash\ncurl -X POST http://localhost:8000/api/v1/change-events \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"source\": \"github\",\n    \"repo\": \"org/repo\",\n    \"sha\": \"abc123\",\n    \"pr_number\": 42,\n    \"branch\": \"feature-branch\",\n    \"files\": [\"k8s/deployment.yaml\"],\n    \"diff_hunks\": [{\n      \"file\": \"k8s/deployment.yaml\",\n      \"hunk\": \"- limits:\\n  cpu: 500m\"\n    }],\n    \"timestamp\": \"2026-01-01T00:00:00Z\"\n  }'\n```\n\n### Get Decisions\n\n```bash\ncurl http://localhost:8000/api/v1/decisions?limit=10\n```\n\n### Get Analytics\n\n```bash\ncurl http://localhost:8000/api/v1/analytics/summary\n```\n\nSee `/docs` for interactive API documentation.\n\n## 🚢 Deployment\n\n### Docker Compose (Recommended for Quick Start)\n\n```bash\ndocker compose up -d\n```\n\n### Kubernetes (Helm)\n\n```bash\n# Install backend\nhelm install patchpulse-backend ./helm/backend \\\n  --namespace patchpulse \\\n  --create-namespace \\\n  --set policy.mode=advisory \\\n  --set ai.openaiApiKey=your_key_here\n\n# Install agent\nhelm install patchpulse-agent ./helm/agent \\\n  --namespace patchpulse \\\n  --set backend.url=http://patchpulse-backend:8000\n```\n\n### Production Considerations\n\n- Use environment variables for secrets (never hardcode)\n- Set up proper TLS/SSL certificates\n- Configure database backups\n- Set up monitoring and alerting\n- Use a managed PostgreSQL database for production\n\n## 🛠️ Development\n\n### Local Development Setup\n\n```bash\n# Backend\ncd app/backend\npython -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\npip install -r requirements.txt\nuvicorn main:app --reload\n\n# Agent\ncd app/agent\ngo run cmd/agent/main.go\n\n# Git Integration\ncd app/integrations/git\npython poller.py\n```\n\n### Running Tests\n\n```bash\n# Unit tests\ncd app/backend\npytest tests/\n\n# Integration tests\ndocker compose up -d\n./test_api_endpoints.sh\n```\n\n### Project Structure\n\n```\npatchpulse/\n├── app/                    # Application code\n│   ├── backend/           # FastAPI backend service\n│   │   ├── main.py        # Main application entry point\n│   │   ├── models.py      # Pydantic models and SQLAlchemy ORM\n│   │   ├── database.py    # Database connection and setup\n│   │   ├── policy_engine.py # Policy evaluation and guardrails\n│   │   ├── ai_analyzer.py # AI-powered risk analysis (BYO LLM!)\n│   │   ├── ai_features.py # Advanced AI features\n│   │   ├── auth.py        # Authentication system\n│   │   └── requirements.txt\n│   ├── agent/             # Kubernetes agent (Go)\n│   │   ├── cmd/agent/     # Agent main application\n│   │   └── Dockerfile\n│   ├── integrations/     # External integrations\n│   │   ├── git/           # GitHub/GitLab integration\n│   │   └── slack/         # Slack notifications\n│   └── ui/                # Dashboard UI\n├── docs/                  # Technical documentation\n├── helm/                  # Kubernetes Helm charts\n├── docker-compose.yml     # Local development setup\n└── README.md             # This file\n```\n\n## 🛡️ Security\n\n- **API keys never exposed** in logs or responses\n- **Least-privilege RBAC** for agent\n- **Encrypted database** connections\n- **TLS** for all API communications\n- **Audit logging** for all decisions\n- **Rate limiting** on API endpoints\n- **Self-hosted** - your data stays on your infrastructure\n\nSee [SECURITY.md](SECURITY.md) for detailed security information.\n\n## 🤝 Contributing\n\nWe welcome contributions! PatchPulse is 100% open source and community-driven.\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n## 📄 License\n\nThis project is licensed under the **PatchPulse Non-Commercial License** - see the [LICENSE](LICENSE) file for details.\n\n**✅ Permitted Uses:**\n- Personal use\n- Educational use\n- Research and development\n- Internal use within non-profit organizations\n- Contributing to the PatchPulse project\n- Forking and modifying for personal/educational purposes\n\n**❌ Prohibited Uses:**\n- Commercial use (selling, licensing, or providing as a service)\n- Use in commercial products or services\n- Reselling or redistributing for profit\n- Use by for-profit companies without explicit written permission\n\n**💼 Commercial Licensing:**\nFor commercial use, please contact us to obtain a commercial license. Commercial licenses are available for:\n- SaaS providers\n- Enterprise deployments\n- Commercial products incorporating PatchPulse\n- Consulting services using PatchPulse\n\n**Contact:** licensing@patchpulse.dev\n\nThis license protects the open-source nature of PatchPulse while ensuring commercial use requires proper licensing.\n\n## 🆘 Support\n\n- **Documentation**: http://localhost:8000/docs (when running locally)\n- **Issues**: https://github.com/amarkdotdev/patchpulse/issues\n- **Discussions**: https://github.com/amarkdotdev/patchpulse/discussions\n\n## 🎯 Roadmap\n\n- [ ] Multi-tenant support (in progress)\n- [ ] Custom guardrail DSL\n- [ ] Integration with more Git providers\n- [ ] Additional AI provider support\n- [ ] Compliance reporting\n- [ ] Enhanced documentation\n- [ ] Local LLM support (Ollama, LocalAI)\n\n## 👨‍💻 About the Creator\n\nPatchPulse was created by **Aaron Mark**, a passionate DevOps engineer from **Israel** 🇮🇱. \n\nAfter experiencing countless production incidents that could have been prevented, Aaron built PatchPulse to help engineering teams ship with confidence. Israel is Aaron's home, and it's from this innovative tech ecosystem that PatchPulse was born.\n\nThe project reflects the values of the Israeli tech community: innovation, pragmatism, and a focus on solving real problems that engineers face every day.\n\n## 🙏 Acknowledgments\n\nBuilt with ❤️ by the open source community. Special thanks to all contributors!\n\n---\n\n**🔓 Open Source | 🤖 Bring Your Own LLM | 🚀 Self-Hosted**\n\n**Made with ❤️ in Israel for the Kubernetes community worldwide**\n"}, "05555e61251f956131b8edcf9e57d8bc096d3969": {"t": 1785764240.7557986, "n": 13782, "h": "893e2e2808597411", "c": "# PatchPulse\n\n**🔓 100% Open Source | 🤖 Bring Your Own LLM | 🚀 Self-Hosted Kubernetes Risk Analysis**\n\nPatchPulse is a self-hosted, open-source solution that prevents production incidents by analyzing infrastructure changes and cluster signals before deployment. It combines rule-based guardrails with AI-powered analysis to provide explainable risk scores and automated enforcement.\n\n## ✨ Key Features\n\n- **🔓 Fully Open Source** - Non-commercial license, no vendor lock-in\n- **🤖 Bring Your Own LLM** - Use OpenAI, DeepSeek, Claude, Gemini, or any OpenAI-compatible API\n- **🏠 Self-Hosted** - Your data stays on your infrastructure\n- **🛡️ 11+ Guardrails** - Rule-based checks for Kubernetes best practices\n- **🧠 AI-Powered Analysis** - Security scanning, recommendations, incident prediction\n- **⚡ Real-Time** - WebSocket updates and instant notifications\n- **🔌 Integrations** - GitHub, GitLab, Slack, Teams, PagerDuty, Email\n- **📊 Enterprise Features** - Admission webhooks, policy bundles, SBOM verification, multi-tenancy\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Docker (running)\n- Python 3.11+ (for local development)\n- Go 1.21+ (for agent development)\n- kubectl (for Kubernetes integration)\n\n### 1. Clone the Repository\n\n```bash\ngit clone https://github.com/amarkdotdev/patchpulse.git\ncd patchpulse\n```\n\n### 2. Configure Your LLM Provider\n\nPatchPulse supports multiple AI providers. **You only need to provide an API key for ONE provider:**\n\n```bash\n# Create .env file\ntouch .env\n\n# Option 1: OpenAI (recommended for best results)\necho \"OPENAI_API_KEY=sk-your-key-here\" >> .env\n\n# Option 2: DeepSeek (cost-effective alternative)\n# echo \"DEEPSEEK_API_KEY=sk-your-key-here\" >> .env\n\n# Option 3: Claude (Anthropic)\n# echo \"ANTHROPIC_API_KEY=sk-ant-your-key-here\" >> .env\n# Note: Requires: pip install anthropic\n\n# Option 4: Google Gemini\n# echo \"GEMINI_API_KEY=your-key-here\" >> .env\n# Note: Requires: pip install google-generativeai\n\n# Optionally specify which provider to use (defaults to first available)\n# echo \"AI_PROVIDER=openai\" >> .env\n```\n\n**💡 No LLM? No Problem!** PatchPulse works without AI - you'll get rule-based guardrails and risk scoring. AI features will be disabled gracefully.\n\n### 3. Start PatchPulse\n\n```bash\n# Start all services\ndocker compose up -d\n\n# Check logs\ndocker compose logs -f backend\n\n# Wait for services to be ready (about 10-15 seconds)\n```\n\n### 4. Access the Application\n\n- **Website**: http://localhost:8000/\n- **Dashboard**: http://localhost:8000/dashboard\n- **API Docs**: http://localhost:8000/docs\n- **Health Check**: http://localhost:8000/health\n\n### 5. Create Your First Account\n\n1. Go to http://localhost:8000/signup\n2. Create an account\n3. Start using PatchPulse!\n\n## 📖 Table of Contents\n\n- [Architecture](#-architecture)\n- [Configuration](#-configuration)\n- [LLM Provider Setup](#-llm-provider-setup)\n- [API Usage](#-api-usage)\n- [Deployment](#-deployment)\n- [Development](#-development)\n- [Contributing](#-contributing)\n- [License](#-license)\n\n## 🏗️ Architecture\n\n### Components\n\n1. **Backend (FastAPI)**\n   - REST API for change events and decisions\n   - Policy engine with 11+ guardrails\n   - AI-powered risk analysis (bring your own LLM!)\n   - PostgreSQL database for persistence\n   - WebSocket support for real-time updates\n\n2. **Agent (Go)**\n   - Kubernetes cluster monitoring\n   - Resource snapshotting\n   - Event watching\n   - Least-privilege RBAC\n\n3. **Git Integrations**\n   - GitHub PR analysis\n   - GitLab MR analysis\n   - Diff parsing and manifest extraction\n\n4. **Notification Integrations**\n   - Slack notifications with interactive approval buttons\n   - Email notifications\n   - Microsoft Teams integration\n   - PagerDuty integration\n\n5. **Dashboard UI**\n   - Real-time decision monitoring\n   - Risk visualization\n   - Analytics and reporting\n   - Export functionality\n\n### Data Flow\n\n```\n1. Developer creates PR/MR → Git integration detects change\n2. Change event sent to backend → Policy engine evaluates\n3. AI analysis runs (if configured) → Security scan, recommendations, predictions\n4. Risk score calculated (0-100) → Decision made (allow/block)\n5. Notification sent to Slack/Teams → Decision stored in database\n6. Dashboard updates in real-time via WebSocket\n```\n\n## 🔧 Configuration\n\n### Environment Variables\n\nCreate a `.env` file in the root directory:\n\n```bash\n# Database\nDATABASE_URL=postgresql://patchpulse:patchpulse@postgres:5432/patchpulse\n\n# Policy Mode (advisory or enforce)\nPOLICY_MODE=advisory\n\n# Logging\nLOG_LEVEL=INFO\n\n# AI Provider - Choose ONE (see LLM Provider Setup section)\nOPENAI_API_KEY=your_openai_api_key\n# OR\n# DEEPSEEK_API_KEY=your_deepseek_api_key\n# OR\n# ANTHROPIC_API_KEY=your_anthropic_api_key\n# OR\n# GEMINI_API_KEY=your_gemini_api_key\n\n# Optional: Specify which provider to use (defaults to first available)\nAI_PROVIDER=openai\n\n# Git Integration\nGITHUB_TOKEN=your_github_token\nGITHUB_REPOS=owner/repo1,owner/repo2\nGITLAB_TOKEN=your_gitlab_token\nGITLAB_PROJECTS=12345,67890\n\n# JWT Secret (auto-generated if not set)\nJWT_SECRET_KEY=your_jwt_secret\n```\n\n### Policy Modes\n\n- **`advisory`**: Logs decisions but doesn't block changes (default)\n- **`enforce`**: Blocks high-risk changes (score ≥ 70)\n\n## 🤖 LLM Provider Setup\n\nPatchPulse is **100% open source** and supports **bring your own LLM**. You can use any of these providers:\n\n### Supported Providers\n\n| Provider | Cost | Quality | Setup |\n|----------|------|---------|-------|\n| **OpenAI** | $$$ | ⭐⭐⭐⭐⭐ | `OPENAI_API_KEY=sk-...` |\n| **DeepSeek** | $ | ⭐⭐⭐⭐ | `DEEPSEEK_API_KEY=sk-...` |\n| **Claude** | $$$ | ⭐⭐⭐⭐⭐ | `ANTHROPIC_API_KEY=sk-ant-...` |\n| **Gemini** | $$ | ⭐⭐⭐⭐ | `GEMINI_API_KEY=...` |\n\n### OpenAI\n\n```bash\nexport OPENAI_API_KEY=sk-your-key-here\n# Or in .env file:\necho \"OPENAI_API_KEY=sk-your-key-here\" >> .env\n```\n\n**Models**: Uses `gpt-4o-mini` by default (cost-effective). You can modify `ai_analyzer.py` to use other models.\n\n### DeepSeek (Recommended for Cost-Conscious Users)\n\n```bash\nexport DEEPSEEK_API_KEY=sk-your-key-here\n# Or in .env file:\necho \"DEEPSEEK_API_KEY=sk-your-key-here\" >> .env\n```\n\n**Models**: Uses `deepseek-chat` by default. OpenAI-compatible API.\n\n### Claude (Anthropic)\n\n```bash\n# First install the package\npip install anthropic\n\nexport ANTHROPIC_API_KEY=sk-ant-your-key-here\n# Or in .env file:\necho \"ANTHROPIC_API_KEY=sk-ant-your-key-here\" >> .env\n```\n\n**Models**: Uses `claude-3-5-sonnet-20241022` by default.\n\n### Google Gemini\n\n```bash\n# First install the package\npip install google-generativeai\n\nexport GEMINI_API_KEY=your-key-here\n# Or in .env file:\necho \"GEMINI_API_KEY=your-key-here\" >> .env\n```\n\n**Models**: Uses `gemini-1.5-pro` by default.\n\n### Using a Custom OpenAI-Compatible API\n\nPatchPulse supports any OpenAI-compatible API endpoint (Ollama, LocalAI, vLLM, etc.):\n\n```bash\n# Set a dummy API key (not used for local endpoints)\nexport OPENAI_API_KEY=not-used\n\n# Set your custom endpoint\nexport OPENAI_BASE_URL=http://localhost:11434/v1  # Ollama example\n# Or\nexport OPENAI_BASE_URL=http://localhost:8080/v1   # LocalAI example\n\n# Or in .env file:\necho \"OPENAI_API_KEY=not-used\" >> .env\necho \"OPENAI_BASE_URL=http://localhost:11434/v1\" >> .env\n```\n\n**Examples:**\n- **Ollama**: `OPENAI_BASE_URL=http://localhost:11434/v1`\n- **LocalAI**: `OPENAI_BASE_URL=http://localhost:8080/v1`\n- **vLLM**: `OPENAI_BASE_URL=http://localhost:8000/v1`\n- **Any OpenAI-compatible service**: Just set the base URL!\n\nThe system will automatically use your custom endpoint with the OpenAI client.\n\n### No LLM Required\n\n**PatchPulse works perfectly without any LLM!** If no API key is provided:\n- ✅ All rule-based guardrails work\n- ✅ Risk scoring works\n- ✅ All integrations work\n- ✅ Dashboard works\n- ⚠️ AI-powered features are disabled (security scanning, recommendations, predictions)\n\n## 📊 API Usage\n\n### Create Change Event\n\n```bash\ncurl -X POST http://localhost:8000/api/v1/change-events \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"source\": \"github\",\n    \"repo\": \"org/repo\",\n    \"sha\": \"abc123\",\n    \"pr_number\": 42,\n    \"branch\": \"feature-branch\",\n    \"files\": [\"k8s/deployment.yaml\"],\n    \"diff_hunks\": [{\n      \"file\": \"k8s/deployment.yaml\",\n      \"hunk\": \"- limits:\\n  cpu: 500m\"\n    }],\n    \"timestamp\": \"2026-01-01T00:00:00Z\"\n  }'\n```\n\n### Get Decisions\n\n```bash\ncurl http://localhost:8000/api/v1/decisions?limit=10\n```\n\n### Get Analytics\n\n```bash\ncurl http://localhost:8000/api/v1/analytics/summary\n```\n\nSee `/docs` for interactive API documentation.\n\n## 🚢 Deployment\n\n### Docker Compose (Recommended for Quick Start)\n\n```bash\ndocker compose up -d\n```\n\n### Kubernetes (Helm)\n\n```bash\n# Install backend\nhelm install patchpulse-backend ./helm/backend \\\n  --namespace patchpulse \\\n  --create-namespace \\\n  --set policy.mode=advisory \\\n  --set ai.openaiApiKey=your_key_here\n\n# Install agent\nhelm install patchpulse-agent ./helm/agent \\\n  --namespace patchpulse \\\n  --set backend.url=http://patchpulse-backend:8000\n```\n\n### Production Considerations\n\n- Use environment variables for secrets (never hardcode)\n- Set up proper TLS/SSL certificates\n- Configure database backups\n- Set up monitoring and alerting\n- Use a managed PostgreSQL database for production\n\n## 🛠️ Development\n\n### Local Development Setup\n\n```bash\n# Backend\ncd app/backend\npython -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\npip install -r requirements.txt\nuvicorn main:app --reload\n\n# Agent\ncd app/agent\ngo run cmd/agent/main.go\n\n# Git Integration\ncd app/integrations/git\npython poller.py\n```\n\n### Running Tests\n\n```bash\n# Unit tests\ncd app/backend\npytest tests/\n\n# Integration tests\ndocker compose up -d\n./test_api_endpoints.sh\n```\n\n### Project Structure\n\n```\npatchpulse/\n├── app/                    # Application code\n│   ├── backend/           # FastAPI backend service\n│   │   ├── main.py        # Main application entry point\n│   │   ├── models.py      # Pydantic models and SQLAlchemy ORM\n│   │   ├── database.py    # Database connection and setup\n│   │   ├── policy_engine.py # Policy evaluation and guardrails\n│   │   ├── ai_analyzer.py # AI-powered risk analysis (BYO LLM!)\n│   │   ├── ai_features.py # Advanced AI features\n│   │   ├── auth.py        # Authentication system\n│   │   └── requirements.txt\n│   ├── agent/             # Kubernetes agent (Go)\n│   │   ├── cmd/agent/     # Agent main application\n│   │   └── Dockerfile\n│   ├── integrations/     # External integrations\n│   │   ├── git/           # GitHub/GitLab integration\n│   │   └── slack/         # Slack notifications\n│   └── ui/                # Dashboard UI\n├── docs/                  # Technical documentation\n├── helm/                  # Kubernetes Helm charts\n├── docker-compose.yml     # Local development setup\n└── README.md             # This file\n```\n\n## 🛡️ Security\n\n- **API keys never exposed** in logs or responses\n- **Least-privilege RBAC** for agent\n- **Encrypted database** connections\n- **TLS** for all API communications\n- **Audit logging** for all decisions\n- **Rate limiting** on API endpoints\n- **Self-hosted** - your data stays on your infrastructure\n\nSee [SECURITY.md](SECURITY.md) for detailed security information.\n\n## 🤝 Contributing\n\nWe welcome contributions! PatchPulse is 100% open source and community-driven.\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n## 📄 License\n\nThis project is licensed under the **PatchPulse Non-Commercial License** - see the [LICENSE](LICENSE) file for details.\n\n**✅ Permitted Uses:**\n- Personal use\n- Educational use\n- Research and development\n- Internal use within non-profit organizations\n- Contributing to the PatchPulse project\n- Forking and modifying for personal/educational purposes\n\n**❌ Prohibited Uses:**\n- Commercial use (selling, licensing, or providing as a service)\n- Use in commercial products or services\n- Reselling or redistributing for profit\n- Use by for-profit companies without explicit written permission\n\n**💼 Commercial Licensing:**\nFor commercial use, please contact us to obtain a commercial license. Commercial licenses are available for:\n- SaaS providers\n- Enterprise deployments\n- Commercial products incorporating PatchPulse\n- Consulting services using PatchPulse\n\n**Contact:** licensing@patchpulse.dev\n\nThis license protects the open-source nature of PatchPulse while ensuring commercial use requires proper licensing.\n\n## 🆘 Support\n\n- **Documentation**: http://localhost:8000/docs (when running locally)\n- **Issues**: https://github.com/amarkdotdev/patchpulse/issues\n- **Discussions**: https://github.com/amarkdotdev/patchpulse/discussions\n\n## 🎯 Roadmap\n\n- [ ] Multi-tenant support (in progress)\n- [ ] Custom guardrail DSL\n- [ ] Integration with more Git providers\n- [ ] Additional AI provider support\n- [ ] Compliance reporting\n- [ ] Enhanced documentation\n- [ ] Local LLM support (Ollama, LocalAI)\n\n## 👨‍💻 About the Creator\n\nPatchPulse was created by **Aaron Mark**, a passionate DevOps engineer from **Israel** 🇮🇱. \n\nAfter experiencing countless production incidents that could have been prevented, Aaron built PatchPulse to help engineering teams ship with confidence. Israel is Aaron's home, and it's from this innovative tech ecosystem that PatchPulse was born.\n\nThe project reflects the values of the Israeli tech community: innovation, pragmatism, and a focus on solving real problems that engineers face every day.\n\n## 🙏 Acknowledgments\n\nBuilt with ❤️ by the open source community. Special thanks to all contributors!\n\n---\n\n**🔓 Open Source | 🤖 Bring Your Own LLM | 🚀 Self-Hosted**\n\n**Made with ❤️ in Israel for the Kubernetes community worldwide**\n"}, "94f4661bd7adb046da0df1912339ef38d8604504": {"t": 1785764242.7486787, "n": 13238, "h": "0c4583be11dc9f07", "c": "# PatchPulse\n\n**🔓 100% Open Source | 🤖 Bring Your Own LLM | 🚀 Self-Hosted Kubernetes Risk Analysis**\n\nPatchPulse is a self-hosted, open-source solution that prevents production incidents by analyzing infrastructure changes and cluster signals before deployment. It combines rule-based guardrails with AI-powered analysis to provide explainable risk scores and automated enforcement.\n\n## ✨ Key Features\n\n- **🔓 Fully Open Source** - Non-commercial license, no vendor lock-in\n- **🤖 Bring Your Own LLM** - Use OpenAI, DeepSeek, Claude, Gemini, or any OpenAI-compatible API\n- **🏠 Self-Hosted** - Your data stays on your infrastructure\n- **🛡️ 11+ Guardrails** - Rule-based checks for Kubernetes best practices\n- **🧠 AI-Powered Analysis** - Security scanning, recommendations, incident prediction\n- **⚡ Real-Time** - WebSocket updates and instant notifications\n- **🔌 Integrations** - GitHub, GitLab, Slack, Teams, PagerDuty, Email\n- **📊 Enterprise Features** - Admission webhooks, policy bundles, SBOM verification, multi-tenancy\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Docker (running)\n- Python 3.11+ (for local development)\n- Go 1.21+ (for agent development)\n- kubectl (for Kubernetes integration)\n\n### 1. Clone the Repository\n\n```bash\ngit clone https://github.com/amarkdotdev/patchpulse.git\ncd patchpulse\n```\n\n### 2. Configure Your LLM Provider\n\nPatchPulse supports multiple AI providers. **You only need to provide an API key for ONE provider:**\n\n```bash\n# Create .env file\ntouch .env\n\n# Option 1: OpenAI (recommended for best results)\necho \"OPENAI_API_KEY=sk-your-key-here\" >> .env\n\n# Option 2: DeepSeek (cost-effective alternative)\n# echo \"DEEPSEEK_API_KEY=sk-your-key-here\" >> .env\n\n# Option 3: Claude (Anthropic)\n# echo \"ANTHROPIC_API_KEY=sk-ant-your-key-here\" >> .env\n# Note: Requires: pip install anthropic\n\n# Option 4: Google Gemini\n# echo \"GEMINI_API_KEY=your-key-here\" >> .env\n# Note: Requires: pip install google-generativeai\n\n# Optionally specify which provider to use (defaults to first available)\n# echo \"AI_PROVIDER=openai\" >> .env\n```\n\n**💡 No LLM? No Problem!** PatchPulse works without AI - you'll get rule-based guardrails and risk scoring. AI features will be disabled gracefully.\n\n### 3. Start PatchPulse\n\n```bash\n# Start all services\ndocker compose up -d\n\n# Check logs\ndocker compose logs -f backend\n\n# Wait for services to be ready (about 10-15 seconds)\n```\n\n### 4. Access the Application\n\n- **Website**: http://localhost:8000/\n- **Dashboard**: http://localhost:8000/dashboard\n- **API Docs**: http://localhost:8000/docs\n- **Health Check**: http://localhost:8000/health\n\n### 5. Create Your First Account\n\n1. Go to http://localhost:8000/signup\n2. Create an account\n3. Start using PatchPulse!\n\n## 📖 Table of Contents\n\n- [Architecture](#-architecture)\n- [Configuration](#-configuration)\n- [LLM Provider Setup](#-llm-provider-setup)\n- [API Usage](#-api-usage)\n- [Deployment](#-deployment)\n- [Development](#-development)\n- [Contributing](#-contributing)\n- [License](#-license)\n\n## 🏗️ Architecture\n\n### Components\n\n1. **Backend (FastAPI)**\n   - REST API for change events and decisions\n   - Policy engine with 11+ guardrails\n   - AI-powered risk analysis (bring your own LLM!)\n   - PostgreSQL database for persistence\n   - WebSocket support for real-time updates\n\n2. **Agent (Go)**\n   - Kubernetes cluster monitoring\n   - Resource snapshotting\n   - Event watching\n   - Least-privilege RBAC\n\n3. **Git Integrations**\n   - GitHub PR analysis\n   - GitLab MR analysis\n   - Diff parsing and manifest extraction\n\n4. **Notification Integrations**\n   - Slack notifications with interactive approval buttons\n   - Email notifications\n   - Microsoft Teams integration\n   - PagerDuty integration\n\n5. **Dashboard UI**\n   - Real-time decision monitoring\n   - Risk visualization\n   - Analytics and reporting\n   - Export functionality\n\n### Data Flow\n\n```\n1. Developer creates PR/MR → Git integration detects change\n2. Change event sent to backend → Policy engine evaluates\n3. AI analysis runs (if configured) → Security scan, recommendations, predictions\n4. Risk score calculated (0-100) → Decision made (allow/block)\n5. Notification sent to Slack/Teams → Decision stored in database\n6. Dashboard updates in real-time via WebSocket\n```\n\n## 🔧 Configuration\n\n### Environment Variables\n\nCreate a `.env` file in the root directory:\n\n```bash\n# Database\nDATABASE_URL=postgresql://patchpulse:patchpulse@postgres:5432/patchpulse\n\n# Policy Mode (advisory or enforce)\nPOLICY_MODE=advisory\n\n# Logging\nLOG_LEVEL=INFO\n\n# AI Provider - Choose ONE (see LLM Provider Setup section)\nOPENAI_API_KEY=your_openai_api_key\n# OR\n# DEEPSEEK_API_KEY=your_deepseek_api_key\n# OR\n# ANTHROPIC_API_KEY=your_anthropic_api_key\n# OR\n# GEMINI_API_KEY=your_gemini_api_key\n\n# Optional: Specify which provider to use (defaults to first available)\nAI_PROVIDER=openai\n\n# Git Integration\nGITHUB_TOKEN=your_github_token\nGITHUB_REPOS=owner/repo1,owner/repo2\nGITLAB_TOKEN=your_gitlab_token\nGITLAB_PROJECTS=12345,67890\n\n# JWT Secret (auto-generated if not set)\nJWT_SECRET_KEY=your_jwt_secret\n```\n\n### Policy Modes\n\n- **`advisory`**: Logs decisions but doesn't block changes (default)\n- **`enforce`**: Blocks high-risk changes (score ≥ 70)\n\n## 🤖 LLM Provider Setup\n\nPatchPulse is **100% open source** and supports **bring your own LLM**. You can use any of these providers:\n\n### Supported Providers\n\n| Provider | Cost | Quality | Setup |\n|----------|------|---------|-------|\n| **OpenAI** | $$$ | ⭐⭐⭐⭐⭐ | `OPENAI_API_KEY=sk-...` |\n| **DeepSeek** | $ | ⭐⭐⭐⭐ | `DEEPSEEK_API_KEY=sk-...` |\n| **Claude** | $$$ | ⭐⭐⭐⭐⭐ | `ANTHROPIC_API_KEY=sk-ant-...` |\n| **Gemini** | $$ | ⭐⭐⭐⭐ | `GEMINI_API_KEY=...` |\n\n### OpenAI\n\n```bash\nexport OPENAI_API_KEY=sk-your-key-here\n# Or in .env file:\necho \"OPENAI_API_KEY=sk-your-key-here\" >> .env\n```\n\n**Models**: Uses `gpt-4o-mini` by default (cost-effective). You can modify `ai_analyzer.py` to use other models.\n\n### DeepSeek (Recommended for Cost-Conscious Users)\n\n```bash\nexport DEEPSEEK_API_KEY=sk-your-key-here\n# Or in .env file:\necho \"DEEPSEEK_API_KEY=sk-your-key-here\" >> .env\n```\n\n**Models**: Uses `deepseek-chat` by default. OpenAI-compatible API.\n\n### Claude (Anthropic)\n\n```bash\n# First install the package\npip install anthropic\n\nexport ANTHROPIC_API_KEY=sk-ant-your-key-here\n# Or in .env file:\necho \"ANTHROPIC_API_KEY=sk-ant-your-key-here\" >> .env\n```\n\n**Models**: Uses `claude-3-5-sonnet-20241022` by default.\n\n### Google Gemini\n\n```bash\n# First install the package\npip install google-generativeai\n\nexport GEMINI_API_KEY=your-key-here\n# Or in .env file:\necho \"GEMINI_API_KEY=your-key-here\" >> .env\n```\n\n**Models**: Uses `gemini-1.5-pro` by default.\n\n### Using a Custom OpenAI-Compatible API\n\nPatchPulse supports any OpenAI-compatible API endpoint (Ollama, LocalAI, vLLM, etc.):\n\n```bash\n# Set a dummy API key (not used for local endpoints)\nexport OPENAI_API_KEY=not-used\n\n# Set your custom endpoint\nexport OPENAI_BASE_URL=http://localhost:11434/v1  # Ollama example\n# Or\nexport OPENAI_BASE_URL=http://localhost:8080/v1   # LocalAI example\n\n# Or in .env file:\necho \"OPENAI_API_KEY=not-used\" >> .env\necho \"OPENAI_BASE_URL=http://localhost:11434/v1\" >> .env\n```\n\n**Examples:**\n- **Ollama**: `OPENAI_BASE_URL=http://localhost:11434/v1`\n- **LocalAI**: `OPENAI_BASE_URL=http://localhost:8080/v1`\n- **vLLM**: `OPENAI_BASE_URL=http://localhost:8000/v1`\n- **Any OpenAI-compatible service**: Just set the base URL!\n\nThe system will automatically use your custom endpoint with the OpenAI client.\n\n### No LLM Required\n\n**PatchPulse works perfectly without any LLM!** If no API key is provided:\n- ✅ All rule-based guardrails work\n- ✅ Risk scoring works\n- ✅ All integrations work\n- ✅ Dashboard works\n- ⚠️ AI-powered features are disabled (security scanning, recommendations, predictions)\n\n## 📊 API Usage\n\n### Create Change Event\n\n```bash\ncurl -X POST http://localhost:8000/api/v1/change-events \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"source\": \"github\",\n    \"repo\": \"org/repo\",\n    \"sha\": \"abc123\",\n    \"pr_number\": 42,\n    \"branch\": \"feature-branch\",\n    \"files\": [\"k8s/deployment.yaml\"],\n    \"diff_hunks\": [{\n      \"file\": \"k8s/deployment.yaml\",\n      \"hunk\": \"- limits:\\n  cpu: 500m\"\n    }],\n    \"timestamp\": \"2026-01-01T00:00:00Z\"\n  }'\n```\n\n### Get Decisions\n\n```bash\ncurl http://localhost:8000/api/v1/decisions?limit=10\n```\n\n### Get Analytics\n\n```bash\ncurl http://localhost:8000/api/v1/analytics/summary\n```\n\nSee `/docs` for interactive API documentation.\n\n## 🚢 Deployment\n\n### Docker Compose (Recommended for Quick Start)\n\n```bash\ndocker compose up -d\n```\n\n### Kubernetes (Helm)\n\n```bash\n# Install backend\nhelm install patchpulse-backend ./helm/backend \\\n  --namespace patchpulse \\\n  --create-namespace \\\n  --set policy.mode=advisory \\\n  --set ai.openaiApiKey=your_key_here\n\n# Install agent\nhelm install patchpulse-agent ./helm/agent \\\n  --namespace patchpulse \\\n  --set backend.url=http://patchpulse-backend:8000\n```\n\n### Production Considerations\n\n- Use environment variables for secrets (never hardcode)\n- Set up proper TLS/SSL certificates\n- Configure database backups\n- Set up monitoring and alerting\n- Use a managed PostgreSQL database for production\n\n## 🛠️ Development\n\n### Local Development Setup\n\n```bash\n# Backend\ncd app/backend\npython -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\npip install -r requirements.txt\nuvicorn main:app --reload\n\n# Agent\ncd app/agent\ngo run cmd/agent/main.go\n\n# Git Integration\ncd app/integrations/git\npython poller.py\n```\n\n### Running Tests\n\n```bash\n# Unit tests\ncd app/backend\npytest tests/\n\n# Integration tests\ndocker compose up -d\n./test_api_endpoints.sh\n```\n\n### Project Structure\n\n```\npatchpulse/\n├── app/                    # Application code\n│   ├── backend/           # FastAPI backend service\n│   │   ├── main.py        # Main application entry point\n│   │   ├── models.py      # Pydantic models and SQLAlchemy ORM\n│   │   ├── database.py    # Database connection and setup\n│   │   ├── policy_engine.py # Policy evaluation and guardrails\n│   │   ├── ai_analyzer.py # AI-powered risk analysis (BYO LLM!)\n│   │   ├── ai_features.py # Advanced AI features\n│   │   ├── auth.py        # Authentication system\n│   │   └── requirements.txt\n│   ├── agent/             # Kubernetes agent (Go)\n│   │   ├── cmd/agent/     # Agent main application\n│   │   └── Dockerfile\n│   ├── integrations/     # External integrations\n│   │   ├── git/           # GitHub/GitLab integration\n│   │   └── slack/         # Slack notifications\n│   └── ui/                # Dashboard UI\n├── docs/                  # Technical documentation\n├── helm/                  # Kubernetes Helm charts\n├── docker-compose.yml     # Local development setup\n└── README.md             # This file\n```\n\n## 🛡️ Security\n\n- **API keys never exposed** in logs or responses\n- **Least-privilege RBAC** for agent\n- **Encrypted database** connections\n- **TLS** for all API communications\n- **Audit logging** for all decisions\n- **Rate limiting** on API endpoints\n- **Self-hosted** - your data stays on your infrastructure\n\nSee [SECURITY.md](SECURITY.md) for detailed security information.\n\n## 🤝 Contributing\n\nWe welcome contributions! PatchPulse is 100% open source and community-driven.\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n## 📄 License\n\nThis project is licensed under the **PatchPulse Non-Commercial License** - see the [LICENSE](LICENSE) file for details.\n\n**✅ Permitted Uses:**\n- Personal use\n- Educational use\n- Research and development\n- Internal use within non-profit organizations\n- Contributing to the PatchPulse project\n- Forking and modifying for personal/educational purposes\n\n**❌ Prohibited Uses:**\n- Commercial use (selling, licensing, or providing as a service)\n- Use in commercial products or services\n- Reselling or redistributing for profit\n- Use by for-profit companies without explicit written permission\n\n**💼 Commercial Licensing:**\nFor commercial use, please contact us to obtain a commercial license. Commercial licenses are available for:\n- SaaS providers\n- Enterprise deployments\n- Commercial products incorporating PatchPulse\n- Consulting services using PatchPulse\n\n**Contact:** licensing@patchpulse.dev\n\nThis license protects the open-source nature of PatchPulse while ensuring commercial use requires proper licensing.\n\n## 🆘 Support\n\n- **Documentation**: http://localhost:8000/docs (when running locally)\n- **Issues**: https://github.com/amarkdotdev/patchpulse/issues\n- **Discussions**: https://github.com/amarkdotdev/patchpulse/discussions\n\n## 🎯 Roadmap\n\n- [ ] Multi-tenant support (in progress)\n- [ ] Custom guardrail DSL\n- [ ] Integration with more Git providers\n- [ ] Additional AI provider support\n- [ ] Compliance reporting\n- [ ] Enhanced documentation\n- [ ] Local LLM support (Ollama, LocalAI)\n\n## 🙏 Acknowledgments\n\nBuilt with ❤️ by the open source community. Special thanks to all contributors!\n\n---\n\n**🔓 Open Source | 🤖 Bring Your Own LLM | 🚀 Self-Hosted**\n\n**Made with ❤️ for the Kubernetes community**\n"}, "6f5399b1925a2fb40b356489c5f617b7e0074713": {"t": 1785764244.6289375, "n": 13246, "h": "f3670ef4e5e54957", "c": "# PatchPulse\n\n**🔓 100% Open Source | 🤖 Bring Your Own LLM | 🚀 Self-Hosted Kubernetes Risk Analysis**\n\nPatchPulse is a self-hosted, open-source solution that prevents production incidents by analyzing infrastructure changes and cluster signals before deployment. It combines rule-based guardrails with AI-powered analysis to provide explainable risk scores and automated enforcement.\n\n## ✨ Key Features\n\n- **🔓 Fully Open Source** - Non-commercial license, no vendor lock-in\n- **🤖 Bring Your Own LLM** - Use OpenAI, DeepSeek, Claude, Gemini, or any OpenAI-compatible API\n- **🏠 Self-Hosted** - Your data stays on your infrastructure\n- **🛡️ 11+ Guardrails** - Rule-based checks for Kubernetes best practices\n- **🧠 AI-Powered Analysis** - Security scanning, recommendations, incident prediction\n- **⚡ Real-Time** - WebSocket updates and instant notifications\n- **🔌 Integrations** - GitHub, GitLab, Slack, Teams, PagerDuty, Email\n- **📊 Enterprise Features** - Admission webhooks, policy bundles, SBOM verification, multi-tenancy\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Docker Desktop (running)\n- Python 3.11+ (for local development)\n- Go 1.21+ (for agent development)\n- kubectl (for Kubernetes integration)\n\n### 1. Clone the Repository\n\n```bash\ngit clone https://github.com/amarkdotdev/patchpulse.git\ncd patchpulse\n```\n\n### 2. Configure Your LLM Provider\n\nPatchPulse supports multiple AI providers. **You only need to provide an API key for ONE provider:**\n\n```bash\n# Create .env file\ntouch .env\n\n# Option 1: OpenAI (recommended for best results)\necho \"OPENAI_API_KEY=sk-your-key-here\" >> .env\n\n# Option 2: DeepSeek (cost-effective alternative)\n# echo \"DEEPSEEK_API_KEY=sk-your-key-here\" >> .env\n\n# Option 3: Claude (Anthropic)\n# echo \"ANTHROPIC_API_KEY=sk-ant-your-key-here\" >> .env\n# Note: Requires: pip install anthropic\n\n# Option 4: Google Gemini\n# echo \"GEMINI_API_KEY=your-key-here\" >> .env\n# Note: Requires: pip install google-generativeai\n\n# Optionally specify which provider to use (defaults to first available)\n# echo \"AI_PROVIDER=openai\" >> .env\n```\n\n**💡 No LLM? No Problem!** PatchPulse works without AI - you'll get rule-based guardrails and risk scoring. AI features will be disabled gracefully.\n\n### 3. Start PatchPulse\n\n```bash\n# Start all services\ndocker compose up -d\n\n# Check logs\ndocker compose logs -f backend\n\n# Wait for services to be ready (about 10-15 seconds)\n```\n\n### 4. Access the Application\n\n- **Website**: http://localhost:8000/\n- **Dashboard**: http://localhost:8000/dashboard\n- **API Docs**: http://localhost:8000/docs\n- **Health Check**: http://localhost:8000/health\n\n### 5. Create Your First Account\n\n1. Go to http://localhost:8000/signup\n2. Create an account\n3. Start using PatchPulse!\n\n## 📖 Table of Contents\n\n- [Architecture](#-architecture)\n- [Configuration](#-configuration)\n- [LLM Provider Setup](#-llm-provider-setup)\n- [API Usage](#-api-usage)\n- [Deployment](#-deployment)\n- [Development](#-development)\n- [Contributing](#-contributing)\n- [License](#-license)\n\n## 🏗️ Architecture\n\n### Components\n\n1. **Backend (FastAPI)**\n   - REST API for change events and decisions\n   - Policy engine with 11+ guardrails\n   - AI-powered risk analysis (bring your own LLM!)\n   - PostgreSQL database for persistence\n   - WebSocket support for real-time updates\n\n2. **Agent (Go)**\n   - Kubernetes cluster monitoring\n   - Resource snapshotting\n   - Event watching\n   - Least-privilege RBAC\n\n3. **Git Integrations**\n   - GitHub PR analysis\n   - GitLab MR analysis\n   - Diff parsing and manifest extraction\n\n4. **Notification Integrations**\n   - Slack notifications with interactive approval buttons\n   - Email notifications\n   - Microsoft Teams integration\n   - PagerDuty integration\n\n5. **Dashboard UI**\n   - Real-time decision monitoring\n   - Risk visualization\n   - Analytics and reporting\n   - Export functionality\n\n### Data Flow\n\n```\n1. Developer creates PR/MR → Git integration detects change\n2. Change event sent to backend → Policy engine evaluates\n3. AI analysis runs (if configured) → Security scan, recommendations, predictions\n4. Risk score calculated (0-100) → Decision made (allow/block)\n5. Notification sent to Slack/Teams → Decision stored in database\n6. Dashboard updates in real-time via WebSocket\n```\n\n## 🔧 Configuration\n\n### Environment Variables\n\nCreate a `.env` file in the root directory:\n\n```bash\n# Database\nDATABASE_URL=postgresql://patchpulse:patchpulse@postgres:5432/patchpulse\n\n# Policy Mode (advisory or enforce)\nPOLICY_MODE=advisory\n\n# Logging\nLOG_LEVEL=INFO\n\n# AI Provider - Choose ONE (see LLM Provider Setup section)\nOPENAI_API_KEY=your_openai_api_key\n# OR\n# DEEPSEEK_API_KEY=your_deepseek_api_key\n# OR\n# ANTHROPIC_API_KEY=your_anthropic_api_key\n# OR\n# GEMINI_API_KEY=your_gemini_api_key\n\n# Optional: Specify which provider to use (defaults to first available)\nAI_PROVIDER=openai\n\n# Git Integration\nGITHUB_TOKEN=your_github_token\nGITHUB_REPOS=owner/repo1,owner/repo2\nGITLAB_TOKEN=your_gitlab_token\nGITLAB_PROJECTS=12345,67890\n\n# JWT Secret (auto-generated if not set)\nJWT_SECRET_KEY=your_jwt_secret\n```\n\n### Policy Modes\n\n- **`advisory`**: Logs decisions but doesn't block changes (default)\n- **`enforce`**: Blocks high-risk changes (score ≥ 70)\n\n## 🤖 LLM Provider Setup\n\nPatchPulse is **100% open source** and supports **bring your own LLM**. You can use any of these providers:\n\n### Supported Providers\n\n| Provider | Cost | Quality | Setup |\n|----------|------|---------|-------|\n| **OpenAI** | $$$ | ⭐⭐⭐⭐⭐ | `OPENAI_API_KEY=sk-...` |\n| **DeepSeek** | $ | ⭐⭐⭐⭐ | `DEEPSEEK_API_KEY=sk-...` |\n| **Claude** | $$$ | ⭐⭐⭐⭐⭐ | `ANTHROPIC_API_KEY=sk-ant-...` |\n| **Gemini** | $$ | ⭐⭐⭐⭐ | `GEMINI_API_KEY=...` |\n\n### OpenAI\n\n```bash\nexport OPENAI_API_KEY=sk-your-key-here\n# Or in .env file:\necho \"OPENAI_API_KEY=sk-your-key-here\" >> .env\n```\n\n**Models**: Uses `gpt-4o-mini` by default (cost-effective). You can modify `ai_analyzer.py` to use other models.\n\n### DeepSeek (Recommended for Cost-Conscious Users)\n\n```bash\nexport DEEPSEEK_API_KEY=sk-your-key-here\n# Or in .env file:\necho \"DEEPSEEK_API_KEY=sk-your-key-here\" >> .env\n```\n\n**Models**: Uses `deepseek-chat` by default. OpenAI-compatible API.\n\n### Claude (Anthropic)\n\n```bash\n# First install the package\npip install anthropic\n\nexport ANTHROPIC_API_KEY=sk-ant-your-key-here\n# Or in .env file:\necho \"ANTHROPIC_API_KEY=sk-ant-your-key-here\" >> .env\n```\n\n**Models**: Uses `claude-3-5-sonnet-20241022` by default.\n\n### Google Gemini\n\n```bash\n# First install the package\npip install google-generativeai\n\nexport GEMINI_API_KEY=your-key-here\n# Or in .env file:\necho \"GEMINI_API_KEY=your-key-here\" >> .env\n```\n\n**Models**: Uses `gemini-1.5-pro` by default.\n\n### Using a Custom OpenAI-Compatible API\n\nPatchPulse supports any OpenAI-compatible API endpoint (Ollama, LocalAI, vLLM, etc.):\n\n```bash\n# Set a dummy API key (not used for local endpoints)\nexport OPENAI_API_KEY=not-used\n\n# Set your custom endpoint\nexport OPENAI_BASE_URL=http://localhost:11434/v1  # Ollama example\n# Or\nexport OPENAI_BASE_URL=http://localhost:8080/v1   # LocalAI example\n\n# Or in .env file:\necho \"OPENAI_API_KEY=not-used\" >> .env\necho \"OPENAI_BASE_URL=http://localhost:11434/v1\" >> .env\n```\n\n**Examples:**\n- **Ollama**: `OPENAI_BASE_URL=http://localhost:11434/v1`\n- **LocalAI**: `OPENAI_BASE_URL=http://localhost:8080/v1`\n- **vLLM**: `OPENAI_BASE_URL=http://localhost:8000/v1`\n- **Any OpenAI-compatible service**: Just set the base URL!\n\nThe system will automatically use your custom endpoint with the OpenAI client.\n\n### No LLM Required\n\n**PatchPulse works perfectly without any LLM!** If no API key is provided:\n- ✅ All rule-based guardrails work\n- ✅ Risk scoring works\n- ✅ All integrations work\n- ✅ Dashboard works\n- ⚠️ AI-powered features are disabled (security scanning, recommendations, predictions)\n\n## 📊 API Usage\n\n### Create Change Event\n\n```bash\ncurl -X POST http://localhost:8000/api/v1/change-events \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"source\": \"github\",\n    \"repo\": \"org/repo\",\n    \"sha\": \"abc123\",\n    \"pr_number\": 42,\n    \"branch\": \"feature-branch\",\n    \"files\": [\"k8s/deployment.yaml\"],\n    \"diff_hunks\": [{\n      \"file\": \"k8s/deployment.yaml\",\n      \"hunk\": \"- limits:\\n  cpu: 500m\"\n    }],\n    \"timestamp\": \"2026-01-01T00:00:00Z\"\n  }'\n```\n\n### Get Decisions\n\n```bash\ncurl http://localhost:8000/api/v1/decisions?limit=10\n```\n\n### Get Analytics\n\n```bash\ncurl http://localhost:8000/api/v1/analytics/summary\n```\n\nSee `/docs` for interactive API documentation.\n\n## 🚢 Deployment\n\n### Docker Compose (Recommended for Quick Start)\n\n```bash\ndocker compose up -d\n```\n\n### Kubernetes (Helm)\n\n```bash\n# Install backend\nhelm install patchpulse-backend ./helm/backend \\\n  --namespace patchpulse \\\n  --create-namespace \\\n  --set policy.mode=advisory \\\n  --set ai.openaiApiKey=your_key_here\n\n# Install agent\nhelm install patchpulse-agent ./helm/agent \\\n  --namespace patchpulse \\\n  --set backend.url=http://patchpulse-backend:8000\n```\n\n### Production Considerations\n\n- Use environment variables for secrets (never hardcode)\n- Set up proper TLS/SSL certificates\n- Configure database backups\n- Set up monitoring and alerting\n- Use a managed PostgreSQL database for production\n\n## 🛠️ Development\n\n### Local Development Setup\n\n```bash\n# Backend\ncd app/backend\npython -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\npip install -r requirements.txt\nuvicorn main:app --reload\n\n# Agent\ncd app/agent\ngo run cmd/agent/main.go\n\n# Git Integration\ncd app/integrations/git\npython poller.py\n```\n\n### Running Tests\n\n```bash\n# Unit tests\ncd app/backend\npytest tests/\n\n# Integration tests\ndocker compose up -d\n./test_api_endpoints.sh\n```\n\n### Project Structure\n\n```\npatchpulse/\n├── app/                    # Application code\n│   ├── backend/           # FastAPI backend service\n│   │   ├── main.py        # Main application entry point\n│   │   ├── models.py      # Pydantic models and SQLAlchemy ORM\n│   │   ├── database.py    # Database connection and setup\n│   │   ├── policy_engine.py # Policy evaluation and guardrails\n│   │   ├── ai_analyzer.py # AI-powered risk analysis (BYO LLM!)\n│   │   ├── ai_features.py # Advanced AI features\n│   │   ├── auth.py        # Authentication system\n│   │   └── requirements.txt\n│   ├── agent/             # Kubernetes agent (Go)\n│   │   ├── cmd/agent/     # Agent main application\n│   │   └── Dockerfile\n│   ├── integrations/     # External integrations\n│   │   ├── git/           # GitHub/GitLab integration\n│   │   └── slack/         # Slack notifications\n│   └── ui/                # Dashboard UI\n├── docs/                  # Technical documentation\n├── helm/                  # Kubernetes Helm charts\n├── docker-compose.yml     # Local development setup\n└── README.md             # This file\n```\n\n## 🛡️ Security\n\n- **API keys never exposed** in logs or responses\n- **Least-privilege RBAC** for agent\n- **Encrypted database** connections\n- **TLS** for all API communications\n- **Audit logging** for all decisions\n- **Rate limiting** on API endpoints\n- **Self-hosted** - your data stays on your infrastructure\n\nSee [SECURITY.md](SECURITY.md) for detailed security information.\n\n## 🤝 Contributing\n\nWe welcome contributions! PatchPulse is 100% open source and community-driven.\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n## 📄 License\n\nThis project is licensed under the **PatchPulse Non-Commercial License** - see the [LICENSE](LICENSE) file for details.\n\n**✅ Permitted Uses:**\n- Personal use\n- Educational use\n- Research and development\n- Internal use within non-profit organizations\n- Contributing to the PatchPulse project\n- Forking and modifying for personal/educational purposes\n\n**❌ Prohibited Uses:**\n- Commercial use (selling, licensing, or providing as a service)\n- Use in commercial products or services\n- Reselling or redistributing for profit\n- Use by for-profit companies without explicit written permission\n\n**💼 Commercial Licensing:**\nFor commercial use, please contact us to obtain a commercial license. Commercial licenses are available for:\n- SaaS providers\n- Enterprise deployments\n- Commercial products incorporating PatchPulse\n- Consulting services using PatchPulse\n\n**Contact:** licensing@patchpulse.dev\n\nThis license protects the open-source nature of PatchPulse while ensuring commercial use requires proper licensing.\n\n## 🆘 Support\n\n- **Documentation**: http://localhost:8000/docs (when running locally)\n- **Issues**: https://github.com/amarkdotdev/patchpulse/issues\n- **Discussions**: https://github.com/amarkdotdev/patchpulse/discussions\n\n## 🎯 Roadmap\n\n- [ ] Multi-tenant support (in progress)\n- [ ] Custom guardrail DSL\n- [ ] Integration with more Git providers\n- [ ] Additional AI provider support\n- [ ] Compliance reporting\n- [ ] Enhanced documentation\n- [ ] Local LLM support (Ollama, LocalAI)\n\n## 🙏 Acknowledgments\n\nBuilt with ❤️ by the open source community. Special thanks to all contributors!\n\n---\n\n**🔓 Open Source | 🤖 Bring Your Own LLM | 🚀 Self-Hosted**\n\n**Made with ❤️ for the Kubernetes community**\n"}, "67ee672d06ef00dcce15b3084f1945c871d4f964": {"t": 1785764246.4711118, "n": 12545, "h": "7f291e8c9cfa2988", "c": "# PatchPulse\n\n**🔓 100% Open Source | 🤖 Bring Your Own LLM | 🚀 Self-Hosted Kubernetes Risk Analysis**\n\nPatchPulse is a self-hosted, open-source solution that prevents production incidents by analyzing infrastructure changes and cluster signals before deployment. It combines rule-based guardrails with AI-powered analysis to provide explainable risk scores and automated enforcement.\n\n## ✨ Key Features\n\n- **🔓 Fully Open Source** - MIT License, no vendor lock-in\n- **🤖 Bring Your Own LLM** - Use OpenAI, DeepSeek, Claude, Gemini, or any OpenAI-compatible API\n- **🏠 Self-Hosted** - Your data stays on your infrastructure\n- **🛡️ 11+ Guardrails** - Rule-based checks for Kubernetes best practices\n- **🧠 AI-Powered Analysis** - Security scanning, recommendations, incident prediction\n- **⚡ Real-Time** - WebSocket updates and instant notifications\n- **🔌 Integrations** - GitHub, GitLab, Slack, Teams, PagerDuty, Email\n- **📊 Enterprise Features** - Admission webhooks, policy bundles, SBOM verification, multi-tenancy\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Docker Desktop (running)\n- Python 3.11+ (for local development)\n- Go 1.21+ (for agent development)\n- kubectl (for Kubernetes integration)\n\n### 1. Clone the Repository\n\n```bash\ngit clone https://github.com/amarkdotdev/patchpulse.git\ncd patchpulse\n```\n\n### 2. Configure Your LLM Provider\n\nPatchPulse supports multiple AI providers. **You only need to provide an API key for ONE provider:**\n\n```bash\n# Create .env file\ntouch .env\n\n# Option 1: OpenAI (recommended for best results)\necho \"OPENAI_API_KEY=sk-your-key-here\" >> .env\n\n# Option 2: DeepSeek (cost-effective alternative)\n# echo \"DEEPSEEK_API_KEY=sk-your-key-here\" >> .env\n\n# Option 3: Claude (Anthropic)\n# echo \"ANTHROPIC_API_KEY=sk-ant-your-key-here\" >> .env\n# Note: Requires: pip install anthropic\n\n# Option 4: Google Gemini\n# echo \"GEMINI_API_KEY=your-key-here\" >> .env\n# Note: Requires: pip install google-generativeai\n\n# Optionally specify which provider to use (defaults to first available)\n# echo \"AI_PROVIDER=openai\" >> .env\n```\n\n**💡 No LLM? No Problem!** PatchPulse works without AI - you'll get rule-based guardrails and risk scoring. AI features will be disabled gracefully.\n\n### 3. Start PatchPulse\n\n```bash\n# Start all services\ndocker compose up -d\n\n# Check logs\ndocker compose logs -f backend\n\n# Wait for services to be ready (about 10-15 seconds)\n```\n\n### 4. Access the Application\n\n- **Website**: http://localhost:8000/\n- **Dashboard**: http://localhost:8000/dashboard\n- **API Docs**: http://localhost:8000/docs\n- **Health Check**: http://localhost:8000/health\n\n### 5. Create Your First Account\n\n1. Go to http://localhost:8000/signup\n2. Create an account\n3. Start using PatchPulse!\n\n## 📖 Table of Contents\n\n- [Architecture](#-architecture)\n- [Configuration](#-configuration)\n- [LLM Provider Setup](#-llm-provider-setup)\n- [API Usage](#-api-usage)\n- [Deployment](#-deployment)\n- [Development](#-development)\n- [Contributing](#-contributing)\n- [License](#-license)\n\n## 🏗️ Architecture\n\n### Components\n\n1. **Backend (FastAPI)**\n   - REST API for change events and decisions\n   - Policy engine with 11+ guardrails\n   - AI-powered risk analysis (bring your own LLM!)\n   - PostgreSQL database for persistence\n   - WebSocket support for real-time updates\n\n2. **Agent (Go)**\n   - Kubernetes cluster monitoring\n   - Resource snapshotting\n   - Event watching\n   - Least-privilege RBAC\n\n3. **Git Integrations**\n   - GitHub PR analysis\n   - GitLab MR analysis\n   - Diff parsing and manifest extraction\n\n4. **Notification Integrations**\n   - Slack notifications with interactive approval buttons\n   - Email notifications\n   - Microsoft Teams integration\n   - PagerDuty integration\n\n5. **Dashboard UI**\n   - Real-time decision monitoring\n   - Risk visualization\n   - Analytics and reporting\n   - Export functionality\n\n### Data Flow\n\n```\n1. Developer creates PR/MR → Git integration detects change\n2. Change event sent to backend → Policy engine evaluates\n3. AI analysis runs (if configured) → Security scan, recommendations, predictions\n4. Risk score calculated (0-100) → Decision made (allow/block)\n5. Notification sent to Slack/Teams → Decision stored in database\n6. Dashboard updates in real-time via WebSocket\n```\n\n## 🔧 Configuration\n\n### Environment Variables\n\nCreate a `.env` file in the root directory:\n\n```bash\n# Database\nDATABASE_URL=postgresql://patchpulse:patchpulse@postgres:5432/patchpulse\n\n# Policy Mode (advisory or enforce)\nPOLICY_MODE=advisory\n\n# Logging\nLOG_LEVEL=INFO\n\n# AI Provider - Choose ONE (see LLM Provider Setup section)\nOPENAI_API_KEY=your_openai_api_key\n# OR\n# DEEPSEEK_API_KEY=your_deepseek_api_key\n# OR\n# ANTHROPIC_API_KEY=your_anthropic_api_key\n# OR\n# GEMINI_API_KEY=your_gemini_api_key\n\n# Optional: Specify which provider to use (defaults to first available)\nAI_PROVIDER=openai\n\n# Git Integration\nGITHUB_TOKEN=your_github_token\nGITHUB_REPOS=owner/repo1,owner/repo2\nGITLAB_TOKEN=your_gitlab_token\nGITLAB_PROJECTS=12345,67890\n\n# JWT Secret (auto-generated if not set)\nJWT_SECRET_KEY=your_jwt_secret\n```\n\n### Policy Modes\n\n- **`advisory`**: Logs decisions but doesn't block changes (default)\n- **`enforce`**: Blocks high-risk changes (score ≥ 70)\n\n## 🤖 LLM Provider Setup\n\nPatchPulse is **100% open source** and supports **bring your own LLM**. You can use any of these providers:\n\n### Supported Providers\n\n| Provider | Cost | Quality | Setup |\n|----------|------|---------|-------|\n| **OpenAI** | $$$ | ⭐⭐⭐⭐⭐ | `OPENAI_API_KEY=sk-...` |\n| **DeepSeek** | $ | ⭐⭐⭐⭐ | `DEEPSEEK_API_KEY=sk-...` |\n| **Claude** | $$$ | ⭐⭐⭐⭐⭐ | `ANTHROPIC_API_KEY=sk-ant-...` |\n| **Gemini** | $$ | ⭐⭐⭐⭐ | `GEMINI_API_KEY=...` |\n\n### OpenAI\n\n```bash\nexport OPENAI_API_KEY=sk-your-key-here\n# Or in .env file:\necho \"OPENAI_API_KEY=sk-your-key-here\" >> .env\n```\n\n**Models**: Uses `gpt-4o-mini` by default (cost-effective). You can modify `ai_analyzer.py` to use other models.\n\n### DeepSeek (Recommended for Cost-Conscious Users)\n\n```bash\nexport DEEPSEEK_API_KEY=sk-your-key-here\n# Or in .env file:\necho \"DEEPSEEK_API_KEY=sk-your-key-here\" >> .env\n```\n\n**Models**: Uses `deepseek-chat` by default. OpenAI-compatible API.\n\n### Claude (Anthropic)\n\n```bash\n# First install the package\npip install anthropic\n\nexport ANTHROPIC_API_KEY=sk-ant-your-key-here\n# Or in .env file:\necho \"ANTHROPIC_API_KEY=sk-ant-your-key-here\" >> .env\n```\n\n**Models**: Uses `claude-3-5-sonnet-20241022` by default.\n\n### Google Gemini\n\n```bash\n# First install the package\npip install google-generativeai\n\nexport GEMINI_API_KEY=your-key-here\n# Or in .env file:\necho \"GEMINI_API_KEY=your-key-here\" >> .env\n```\n\n**Models**: Uses `gemini-1.5-pro` by default.\n\n### Using a Custom OpenAI-Compatible API\n\nPatchPulse supports any OpenAI-compatible API endpoint (Ollama, LocalAI, vLLM, etc.):\n\n```bash\n# Set a dummy API key (not used for local endpoints)\nexport OPENAI_API_KEY=not-used\n\n# Set your custom endpoint\nexport OPENAI_BASE_URL=http://localhost:11434/v1  # Ollama example\n# Or\nexport OPENAI_BASE_URL=http://localhost:8080/v1   # LocalAI example\n\n# Or in .env file:\necho \"OPENAI_API_KEY=not-used\" >> .env\necho \"OPENAI_BASE_URL=http://localhost:11434/v1\" >> .env\n```\n\n**Examples:**\n- **Ollama**: `OPENAI_BASE_URL=http://localhost:11434/v1`\n- **LocalAI**: `OPENAI_BASE_URL=http://localhost:8080/v1`\n- **vLLM**: `OPENAI_BASE_URL=http://localhost:8000/v1`\n- **Any OpenAI-compatible service**: Just set the base URL!\n\nThe system will automatically use your custom endpoint with the OpenAI client.\n\n### No LLM Required\n\n**PatchPulse works perfectly without any LLM!** If no API key is provided:\n- ✅ All rule-based guardrails work\n- ✅ Risk scoring works\n- ✅ All integrations work\n- ✅ Dashboard works\n- ⚠️ AI-powered features are disabled (security scanning, recommendations, predictions)\n\n## 📊 API Usage\n\n### Create Change Event\n\n```bash\ncurl -X POST http://localhost:8000/api/v1/change-events \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"source\": \"github\",\n    \"repo\": \"org/repo\",\n    \"sha\": \"abc123\",\n    \"pr_number\": 42,\n    \"branch\": \"feature-branch\",\n    \"files\": [\"k8s/deployment.yaml\"],\n    \"diff_hunks\": [{\n      \"file\": \"k8s/deployment.yaml\",\n      \"hunk\": \"- limits:\\n  cpu: 500m\"\n    }],\n    \"timestamp\": \"2026-01-01T00:00:00Z\"\n  }'\n```\n\n### Get Decisions\n\n```bash\ncurl http://localhost:8000/api/v1/decisions?limit=10\n```\n\n### Get Analytics\n\n```bash\ncurl http://localhost:8000/api/v1/analytics/summary\n```\n\nSee `/docs` for interactive API documentation.\n\n## 🚢 Deployment\n\n### Docker Compose (Recommended for Quick Start)\n\n```bash\ndocker compose up -d\n```\n\n### Kubernetes (Helm)\n\n```bash\n# Install backend\nhelm install patchpulse-backend ./helm/backend \\\n  --namespace patchpulse \\\n  --create-namespace \\\n  --set policy.mode=advisory \\\n  --set ai.openaiApiKey=your_key_here\n\n# Install agent\nhelm install patchpulse-agent ./helm/agent \\\n  --namespace patchpulse \\\n  --set backend.url=http://patchpulse-backend:8000\n```\n\n### Production Considerations\n\n- Use environment variables for secrets (never hardcode)\n- Set up proper TLS/SSL certificates\n- Configure database backups\n- Set up monitoring and alerting\n- Use a managed PostgreSQL database for production\n\n## 🛠️ Development\n\n### Local Development Setup\n\n```bash\n# Backend\ncd app/backend\npython -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\npip install -r requirements.txt\nuvicorn main:app --reload\n\n# Agent\ncd app/agent\ngo run cmd/agent/main.go\n\n# Git Integration\ncd app/integrations/git\npython poller.py\n```\n\n### Running Tests\n\n```bash\n# Unit tests\ncd app/backend\npytest tests/\n\n# Integration tests\ndocker compose up -d\n./test_api_endpoints.sh\n```\n\n### Project Structure\n\n```\npatchpulse/\n├── app/                    # Application code\n│   ├── backend/           # FastAPI backend service\n│   │   ├── main.py        # Main application entry point\n│   │   ├── models.py      # Pydantic models and SQLAlchemy ORM\n│   │   ├── database.py    # Database connection and setup\n│   │   ├── policy_engine.py # Policy evaluation and guardrails\n│   │   ├── ai_analyzer.py # AI-powered risk analysis (BYO LLM!)\n│   │   ├── ai_features.py # Advanced AI features\n│   │   ├── auth.py        # Authentication system\n│   │   └── requirements.txt\n│   ├── agent/             # Kubernetes agent (Go)\n│   │   ├── cmd/agent/     # Agent main application\n│   │   └── Dockerfile\n│   ├── integrations/     # External integrations\n│   │   ├── git/           # GitHub/GitLab integration\n│   │   └── slack/         # Slack notifications\n│   └── ui/                # Dashboard UI\n├── docs/                  # Technical documentation\n├── helm/                  # Kubernetes Helm charts\n├── docker-compose.yml     # Local development setup\n└── README.md             # This file\n```\n\n## 🛡️ Security\n\n- **API keys never exposed** in logs or responses\n- **Least-privilege RBAC** for agent\n- **Encrypted database** connections\n- **TLS** for all API communications\n- **Audit logging** for all decisions\n- **Rate limiting** on API endpoints\n- **Self-hosted** - your data stays on your infrastructure\n\nSee [SECURITY.md](SECURITY.md) for detailed security information.\n\n## 🤝 Contributing\n\nWe welcome contributions! PatchPulse is 100% open source and community-driven.\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n## 📄 License\n\nThis project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.\n\n**You are free to:**\n- ✅ Use PatchPulse commercially\n- ✅ Modify the source code\n- ✅ Distribute PatchPulse\n- ✅ Use it privately\n- ✅ Patent use\n- ✅ Place warranty\n\n**You must:**\n- Include the license and copyright notice\n\n## 🆘 Support\n\n- **Documentation**: http://localhost:8000/docs (when running locally)\n- **Issues**: https://github.com/amarkdotdev/patchpulse/issues\n- **Discussions**: https://github.com/amarkdotdev/patchpulse/discussions\n\n## 🎯 Roadmap\n\n- [ ] Multi-tenant support (in progress)\n- [ ] Custom guardrail DSL\n- [ ] Integration with more Git providers\n- [ ] Additional AI provider support\n- [ ] Compliance reporting\n- [ ] Enhanced documentation\n- [ ] Local LLM support (Ollama, LocalAI)\n\n## 🙏 Acknowledgments\n\nBuilt with ❤️ by the open source community. Special thanks to all contributors!\n\n---\n\n**🔓 Open Source | 🤖 Bring Your Own LLM | 🚀 Self-Hosted**\n\n**Made with ❤️ for the Kubernetes community**\n"}, "ef7e0c42084ecc8ad2cc89324bdf3ad5f85430a8": {"t": 1785764248.4173114, "n": 12592, "h": "0cfc110c8d760d68", "c": "# PatchPulse\n\n**🔓 100% Open Source | 🤖 Bring Your Own LLM | 🚀 Self-Hosted Kubernetes Risk Analysis**\n\nPatchPulse is a self-hosted, open-source solution that prevents production incidents by analyzing infrastructure changes and cluster signals before deployment. It combines rule-based guardrails with AI-powered analysis to provide explainable risk scores and automated enforcement.\n\n## ✨ Key Features\n\n- **🔓 Fully Open Source** - MIT License, no vendor lock-in\n- **🤖 Bring Your Own LLM** - Use OpenAI, DeepSeek, Claude, Gemini, or any OpenAI-compatible API\n- **🏠 Self-Hosted** - Your data stays on your infrastructure\n- **🛡️ 11+ Guardrails** - Rule-based checks for Kubernetes best practices\n- **🧠 AI-Powered Analysis** - Security scanning, recommendations, incident prediction\n- **⚡ Real-Time** - WebSocket updates and instant notifications\n- **🔌 Integrations** - GitHub, GitLab, Slack, Teams, PagerDuty, Email\n- **📊 Enterprise Features** - Admission webhooks, policy bundles, SBOM verification, multi-tenancy\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Docker Desktop (running)\n- Python 3.11+ (for local development)\n- Go 1.21+ (for agent development)\n- kubectl (for Kubernetes integration)\n\n### 1. Clone the Repository\n\n```bash\ngit clone https://github.com/amarkdotdev/patchpulse.git\ncd patchpulse\n```\n\n### 2. Configure Your LLM Provider\n\nPatchPulse supports multiple AI providers. **You only need to provide an API key for ONE provider:**\n\n```bash\n# Create .env file\ntouch .env\n\n# Option 1: OpenAI (recommended for best results)\necho \"OPENAI_API_KEY=sk-your-key-here\" >> .env\n\n# Option 2: DeepSeek (cost-effective alternative)\n# echo \"DEEPSEEK_API_KEY=sk-your-key-here\" >> .env\n\n# Option 3: Claude (Anthropic)\n# echo \"ANTHROPIC_API_KEY=sk-ant-your-key-here\" >> .env\n# Note: Requires: pip install anthropic\n\n# Option 4: Google Gemini\n# echo \"GEMINI_API_KEY=your-key-here\" >> .env\n# Note: Requires: pip install google-generativeai\n\n# Optionally specify which provider to use (defaults to first available)\n# echo \"AI_PROVIDER=openai\" >> .env\n```\n\n**💡 No LLM? No Problem!** PatchPulse works without AI - you'll get rule-based guardrails and risk scoring. AI features will be disabled gracefully.\n\n### 3. Start PatchPulse\n\n```bash\n# Start all services\ndocker compose up -d\n\n# Check logs\ndocker compose logs -f backend\n\n# Wait for services to be ready (about 10-15 seconds)\n```\n\n### 4. Access the Application\n\n- **Website**: http://localhost:8000/\n- **Dashboard**: http://localhost:8000/dashboard\n- **API Docs**: http://localhost:8000/docs\n- **Health Check**: http://localhost:8000/health\n\n### 5. Create Your First Account\n\n1. Go to http://localhost:8000/signup\n2. Create an account\n3. Start using PatchPulse!\n\n## 📖 Table of Contents\n\n- [Architecture](#-architecture)\n- [Configuration](#-configuration)\n- [LLM Provider Setup](#-llm-provider-setup)\n- [API Usage](#-api-usage)\n- [Deployment](#-deployment)\n- [Development](#-development)\n- [Contributing](#-contributing)\n- [License](#-license)\n\n## 🏗️ Architecture\n\n### Components\n\n1. **Backend (FastAPI)**\n   - REST API for change events and decisions\n   - Policy engine with 11+ guardrails\n   - AI-powered risk analysis (bring your own LLM!)\n   - PostgreSQL database for persistence\n   - WebSocket support for real-time updates\n\n2. **Agent (Go)**\n   - Kubernetes cluster monitoring\n   - Resource snapshotting\n   - Event watching\n   - Least-privilege RBAC\n\n3. **Git Integrations**\n   - GitHub PR analysis\n   - GitLab MR analysis\n   - Diff parsing and manifest extraction\n\n4. **Notification Integrations**\n   - Slack notifications with interactive approval buttons\n   - Email notifications\n   - Microsoft Teams integration\n   - PagerDuty integration\n\n5. **Dashboard UI**\n   - Real-time decision monitoring\n   - Risk visualization\n   - Analytics and reporting\n   - Export functionality\n\n### Data Flow\n\n```\n1. Developer creates PR/MR → Git integration detects change\n2. Change event sent to backend → Policy engine evaluates\n3. AI analysis runs (if configured) → Security scan, recommendations, predictions\n4. Risk score calculated (0-100) → Decision made (allow/block)\n5. Notification sent to Slack/Teams → Decision stored in database\n6. Dashboard updates in real-time via WebSocket\n```\n\n## 🔧 Configuration\n\n### Environment Variables\n\nCreate a `.env` file in the root directory:\n\n```bash\n# Database\nDATABASE_URL=postgresql://patchpulse:patchpulse@postgres:5432/patchpulse\n\n# Policy Mode (advisory or enforce)\nPOLICY_MODE=advisory\n\n# Logging\nLOG_LEVEL=INFO\n\n# AI Provider - Choose ONE (see LLM Provider Setup section)\nOPENAI_API_KEY=your_openai_api_key\n# OR\n# DEEPSEEK_API_KEY=your_deepseek_api_key\n# OR\n# ANTHROPIC_API_KEY=your_anthropic_api_key\n# OR\n# GEMINI_API_KEY=your_gemini_api_key\n\n# Optional: Specify which provider to use (defaults to first available)\nAI_PROVIDER=openai\n\n# Git Integration\nGITHUB_TOKEN=your_github_token\nGITHUB_REPOS=owner/repo1,owner/repo2\nGITLAB_TOKEN=your_gitlab_token\nGITLAB_PROJECTS=12345,67890\n\n# JWT Secret (auto-generated if not set)\nJWT_SECRET_KEY=your_jwt_secret\n```\n\n### Policy Modes\n\n- **`advisory`**: Logs decisions but doesn't block changes (default)\n- **`enforce`**: Blocks high-risk changes (score ≥ 70)\n\n## 🤖 LLM Provider Setup\n\nPatchPulse is **100% open source** and supports **bring your own LLM**. You can use any of these providers:\n\n### Supported Providers\n\n| Provider | Cost | Quality | Setup |\n|----------|------|---------|-------|\n| **OpenAI** | $$$ | ⭐⭐⭐⭐⭐ | `OPENAI_API_KEY=sk-...` |\n| **DeepSeek** | $ | ⭐⭐⭐⭐ | `DEEPSEEK_API_KEY=sk-...` |\n| **Claude** | $$$ | ⭐⭐⭐⭐⭐ | `ANTHROPIC_API_KEY=sk-ant-...` |\n| **Gemini** | $$ | ⭐⭐⭐⭐ | `GEMINI_API_KEY=...` |\n\n### OpenAI\n\n```bash\nexport OPENAI_API_KEY=sk-your-key-here\n# Or in .env file:\necho \"OPENAI_API_KEY=sk-your-key-here\" >> .env\n```\n\n**Models**: Uses `gpt-4o-mini` by default (cost-effective). You can modify `ai_analyzer.py` to use other models.\n\n### DeepSeek (Recommended for Cost-Conscious Users)\n\n```bash\nexport DEEPSEEK_API_KEY=sk-your-key-here\n# Or in .env file:\necho \"DEEPSEEK_API_KEY=sk-your-key-here\" >> .env\n```\n\n**Models**: Uses `deepseek-chat` by default. OpenAI-compatible API.\n\n### Claude (Anthropic)\n\n```bash\n# First install the package\npip install anthropic\n\nexport ANTHROPIC_API_KEY=sk-ant-your-key-here\n# Or in .env file:\necho \"ANTHROPIC_API_KEY=sk-ant-your-key-here\" >> .env\n```\n\n**Models**: Uses `claude-3-5-sonnet-20241022` by default.\n\n### Google Gemini\n\n```bash\n# First install the package\npip install google-generativeai\n\nexport GEMINI_API_KEY=your-key-here\n# Or in .env file:\necho \"GEMINI_API_KEY=your-key-here\" >> .env\n```\n\n**Models**: Uses `gemini-1.5-pro` by default.\n\n### Using a Custom OpenAI-Compatible API\n\nPatchPulse supports any OpenAI-compatible API endpoint (Ollama, LocalAI, vLLM, etc.):\n\n```bash\n# Set a dummy API key (not used for local endpoints)\nexport OPENAI_API_KEY=not-used\n\n# Set your custom endpoint\nexport OPENAI_BASE_URL=http://localhost:11434/v1  # Ollama example\n# Or\nexport OPENAI_BASE_URL=http://localhost:8080/v1   # LocalAI example\n\n# Or in .env file:\necho \"OPENAI_API_KEY=not-used\" >> .env\necho \"OPENAI_BASE_URL=http://localhost:11434/v1\" >> .env\n```\n\n**Examples:**\n- **Ollama**: `OPENAI_BASE_URL=http://localhost:11434/v1`\n- **LocalAI**: `OPENAI_BASE_URL=http://localhost:8080/v1`\n- **vLLM**: `OPENAI_BASE_URL=http://localhost:8000/v1`\n- **Any OpenAI-compatible service**: Just set the base URL!\n\nThe system will automatically use your custom endpoint with the OpenAI client.\n\n### No LLM Required\n\n**PatchPulse works perfectly without any LLM!** If no API key is provided:\n- ✅ All rule-based guardrails work\n- ✅ Risk scoring works\n- ✅ All integrations work\n- ✅ Dashboard works\n- ⚠️ AI-powered features are disabled (security scanning, recommendations, predictions)\n\n## 📊 API Usage\n\n### Create Change Event\n\n```bash\ncurl -X POST http://localhost:8000/api/v1/change-events \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"source\": \"github\",\n    \"repo\": \"org/repo\",\n    \"sha\": \"abc123\",\n    \"pr_number\": 42,\n    \"branch\": \"feature-branch\",\n    \"files\": [\"k8s/deployment.yaml\"],\n    \"diff_hunks\": [{\n      \"file\": \"k8s/deployment.yaml\",\n      \"hunk\": \"- limits:\\n  cpu: 500m\"\n    }],\n    \"timestamp\": \"2026-01-01T00:00:00Z\"\n  }'\n```\n\n### Get Decisions\n\n```bash\ncurl http://localhost:8000/api/v1/decisions?limit=10\n```\n\n### Get Analytics\n\n```bash\ncurl http://localhost:8000/api/v1/analytics/summary\n```\n\nSee `/docs` for interactive API documentation.\n\n## 🚢 Deployment\n\n### Docker Compose (Recommended for Quick Start)\n\n```bash\ndocker compose up -d\n```\n\n### Kubernetes (Helm)\n\n```bash\n# Install backend\nhelm install patchpulse-backend ./helm/backend \\\n  --namespace patchpulse \\\n  --create-namespace \\\n  --set policy.mode=advisory \\\n  --set ai.openaiApiKey=your_key_here\n\n# Install agent\nhelm install patchpulse-agent ./helm/agent \\\n  --namespace patchpulse \\\n  --set backend.url=http://patchpulse-backend:8000\n```\n\n### Production Considerations\n\n- Use environment variables for secrets (never hardcode)\n- Set up proper TLS/SSL certificates\n- Configure database backups\n- Set up monitoring and alerting\n- Use a managed PostgreSQL database for production\n\n## 🛠️ Development\n\n### Local Development Setup\n\n```bash\n# Backend\ncd app/backend\npython -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\npip install -r requirements.txt\nuvicorn main:app --reload\n\n# Agent\ncd app/agent\ngo run cmd/agent/main.go\n\n# Git Integration\ncd app/integrations/git\npython poller.py\n```\n\n### Running Tests\n\n```bash\n# Unit tests\ncd app/backend\npytest tests/\n\n# Integration tests\ndocker compose up -d\n./test_api_endpoints.sh\n```\n\n### Project Structure\n\n```\npatchpulse/\n├── app/                    # Application code\n│   ├── backend/           # FastAPI backend service\n│   │   ├── main.py        # Main application entry point\n│   │   ├── models.py      # Pydantic models and SQLAlchemy ORM\n│   │   ├── database.py    # Database connection and setup\n│   │   ├── policy_engine.py # Policy evaluation and guardrails\n│   │   ├── ai_analyzer.py # AI-powered risk analysis (BYO LLM!)\n│   │   ├── ai_features.py # Advanced AI features\n│   │   ├── auth.py        # Authentication system\n│   │   └── requirements.txt\n│   ├── agent/             # Kubernetes agent (Go)\n│   │   ├── cmd/agent/     # Agent main application\n│   │   └── Dockerfile\n│   ├── integrations/     # External integrations\n│   │   ├── git/           # GitHub/GitLab integration\n│   │   └── slack/         # Slack notifications\n│   └── ui/                # Dashboard UI\n├── website/               # Marketing website\n├── docs/                  # Technical documentation\n├── helm/                  # Kubernetes Helm charts\n├── docker-compose.yml     # Local development setup\n└── README.md             # This file\n```\n\n## 🛡️ Security\n\n- **API keys never exposed** in logs or responses\n- **Least-privilege RBAC** for agent\n- **Encrypted database** connections\n- **TLS** for all API communications\n- **Audit logging** for all decisions\n- **Rate limiting** on API endpoints\n- **Self-hosted** - your data stays on your infrastructure\n\nSee [SECURITY.md](SECURITY.md) for detailed security information.\n\n## 🤝 Contributing\n\nWe welcome contributions! PatchPulse is 100% open source and community-driven.\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n## 📄 License\n\nThis project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.\n\n**You are free to:**\n- ✅ Use PatchPulse commercially\n- ✅ Modify the source code\n- ✅ Distribute PatchPulse\n- ✅ Use it privately\n- ✅ Patent use\n- ✅ Place warranty\n\n**You must:**\n- Include the license and copyright notice\n\n## 🆘 Support\n\n- **Documentation**: http://localhost:8000/docs (when running locally)\n- **Issues**: https://github.com/amarkdotdev/patchpulse/issues\n- **Discussions**: https://github.com/amarkdotdev/patchpulse/discussions\n\n## 🎯 Roadmap\n\n- [ ] Multi-tenant support (in progress)\n- [ ] Custom guardrail DSL\n- [ ] Integration with more Git providers\n- [ ] Additional AI provider support\n- [ ] Compliance reporting\n- [ ] Enhanced documentation\n- [ ] Local LLM support (Ollama, LocalAI)\n\n## 🙏 Acknowledgments\n\nBuilt with ❤️ by the open source community. Special thanks to all contributors!\n\n---\n\n**🔓 Open Source | 🤖 Bring Your Own LLM | 🚀 Self-Hosted**\n\n**Made with ❤️ for the Kubernetes community**\n"}, "900d1706503d173b0f2b25f394b207cc993baf0b": {"t": 1785764250.2823558, "n": 8895, "h": "80bf738ecc86b21a", "c": "# PatchPulse\n\n**AI-Powered Pre-Flight Risk Analysis for Kubernetes**\n\nPatchPulse prevents production incidents by analyzing infrastructure changes and cluster signals before deployment. It combines rule-based guardrails with AI-powered analysis to provide explainable risk scores and automated enforcement.\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Docker Desktop (running)\n- Python 3.11+ (for local development)\n- Go 1.21+ (for agent development)\n- kubectl (for Kubernetes integration)\n\n### Start with Docker Compose\n\n```bash\n# Clone the repository\ngit clone https://github.com/amarkdotdev/patchpulse.git\ncd patchpulse\n\n# Create .env file with your API keys\necho \"DEEPSEEK_API_KEY=your_key_here\" > .env\n\n# Start all services\ndocker compose up -d\n\n# Check logs\ndocker compose logs -f backend\n\n# Access the application\n# Website: http://localhost:8000/\n# Dashboard: http://localhost:8000/dashboard\n# API Docs: http://localhost:8000/docs\n```\n\n## 📁 Repository Structure\n\n```\npatchpulse/\n├── app/                    # Application code\n│   ├── backend/           # FastAPI backend service\n│   │   ├── main.py        # Main application entry point\n│   │   ├── models.py      # Pydantic models and SQLAlchemy ORM\n│   │   ├── database.py    # Database connection and setup\n│   │   ├── policy_engine.py # Policy evaluation and guardrails\n│   │   ├── ai_analyzer.py # AI-powered risk analysis\n│   │   ├── ai_features.py # Advanced AI features\n│   │   ├── auth.py        # Authentication system\n│   │   ├── security.py    # Security utilities\n│   │   └── requirements.txt\n│   ├── agent/             # Kubernetes agent (Go)\n│   │   ├── cmd/agent/     # Agent main application\n│   │   └── Dockerfile\n│   ├── integrations/     # External integrations\n│   │   ├── git/           # GitHub/GitLab integration\n│   │   └── slack/         # Slack notifications\n│   └── ui/                # Dashboard UI\n│       ├── index.html     # Main dashboard\n│       └── customer-dashboard.html\n├── website/               # Marketing website\n│   ├── index.html         # Landing page\n│   ├── login.html         # Login page\n│   ├── docs/              # Documentation pages\n│   └── ...                # Other marketing pages\n├── docs/                  # Technical documentation\n│   ├── architecture.md    # System architecture\n│   ├── quickstart.md      # Quick start guide\n│   ├── demo.md            # Demo walkthrough\n│   ├── runbooks.md        # Operational runbooks\n│   └── threat-model.md    # Security threat model\n├── helm/                  # Kubernetes Helm charts\n│   ├── backend/           # Backend Helm chart\n│   └── agent/             # Agent Helm chart\n├── test_for_prod/         # Production test environment\n│   ├── setup_cluster.sh   # Setup local k3d cluster\n│   ├── deploy_patchpulse.sh # Deploy PatchPulse\n│   └── trigger_test_events.sh # Trigger test events\n├── docker-compose.yml     # Local development setup\n├── Makefile               # Common development tasks\n└── README.md              # This file\n```\n\n## 🏗️ Architecture\n\n### Components\n\n1. **Backend (FastAPI)**\n   - REST API for change events and decisions\n   - Policy engine with 11+ guardrails\n   - AI-powered risk analysis (DeepSeek API)\n   - PostgreSQL database for persistence\n   - WebSocket support for real-time updates\n\n2. **Agent (Go)**\n   - Kubernetes cluster monitoring\n   - Resource snapshotting\n   - Event watching\n   - Least-privilege RBAC\n\n3. **Git Integrations**\n   - GitHub PR analysis\n   - GitLab MR analysis\n   - Diff parsing and manifest extraction\n\n4. **Slack Integration**\n   - Risk notifications\n   - Interactive approval buttons\n   - Decision summaries\n\n5. **Dashboard UI**\n   - Real-time decision monitoring\n   - Risk visualization\n   - Analytics and reporting\n   - Export functionality\n\n### Data Flow\n\n1. Developer creates PR/MR → Git integration detects change\n2. Change event sent to backend → Policy engine evaluates\n3. AI analysis runs → Security scan, recommendations, predictions\n4. Risk score calculated (0-100) → Decision made (allow/block)\n5. Notification sent to Slack → Decision stored in database\n6. Dashboard updates in real-time via WebSocket\n\n## 🛡️ Features\n\n### AI-Powered Guardrails\n- 11+ rule-based guardrails (resource limits, HPA, security contexts, etc.)\n- AI security vulnerability scanning\n- Explainable decisions with concrete evidence\n\n### Intelligent Risk Analysis\n- Hybrid scoring: 60% rule-based + 40% AI\n- AI recommendations with code-level suggestions\n- Incident prediction based on historical patterns\n- Cost optimization suggestions\n\n### Real-Time Monitoring\n- Kubernetes agent provides cluster intelligence\n- WebSocket updates for instant notifications\n- Risk distribution charts and analytics\n\n### Seamless Integrations\n- GitHub & GitLab native integration\n- Slack notifications with interactive buttons\n- REST API for CI/CD pipelines\n\n### Advanced Analytics\n- Comprehensive dashboards\n- Risk trends and decision history\n- Team performance metrics\n- Export and reporting\n\n### Enterprise Security\n- SOC 2 ready architecture\n- Audit logging\n- RBAC with least privilege\n- Zero API key leakage\n- Encrypted communications\n\n## 🔧 Configuration\n\n### Environment Variables\n\nCreate a `.env` file in the root directory:\n\n```bash\n# Database\nDATABASE_URL=postgresql://patchpulse:patchpulse@postgres:5432/patchpulse\n\n# Policy Mode (advisory or enforce)\nPOLICY_MODE=advisory\n\n# Logging\nLOG_LEVEL=INFO\n\n# AI API Key\nDEEPSEEK_API_KEY=your_deepseek_api_key\n\n# Git Integration\nGITHUB_TOKEN=your_github_token\nGITHUB_REPOS=owner/repo1,owner/repo2\nGITLAB_TOKEN=your_gitlab_token\nGITLAB_PROJECTS=12345,67890\n\n# JWT Secret (auto-generated if not set)\nJWT_SECRET_KEY=your_jwt_secret\n```\n\n### Policy Modes\n\n- **advisory**: Logs decisions but doesn't block changes\n- **enforce**: Blocks high-risk changes (score ≥ 70)\n\n## 📊 API Usage\n\n### Create Change Event\n\n```bash\ncurl -X POST http://localhost:8000/api/v1/change-events \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"source\": \"github\",\n    \"repo\": \"org/repo\",\n    \"sha\": \"abc123\",\n    \"pr_number\": 42,\n    \"branch\": \"feature-branch\",\n    \"files\": [\"k8s/deployment.yaml\"],\n    \"diff_hunks\": [...],\n    \"timestamp\": \"2026-01-01T00:00:00Z\"\n  }'\n```\n\n### Get Decisions\n\n```bash\ncurl http://localhost:8000/api/v1/decisions?limit=10\n```\n\n### Get Analytics\n\n```bash\ncurl http://localhost:8000/api/v1/analytics/summary\n```\n\nSee `/docs` for interactive API documentation.\n\n## 🧪 Testing\n\n### Run Unit Tests\n\n```bash\ncd app/backend\npytest tests/\n```\n\n### Test in Production-Like Environment\n\n```bash\ncd test_for_prod\n./setup_cluster.sh\n./deploy_patchpulse.sh\n./trigger_test_events.sh\n```\n\n## 🚢 Deployment\n\n### Kubernetes (Helm)\n\n```bash\n# Add Helm repository\nhelm repo add patchpulse https://charts.patchpulse.io\nhelm repo update\n\n# Install backend\nhelm install patchpulse-backend patchpulse/backend \\\n  --namespace patchpulse \\\n  --set policy.mode=advisory\n\n# Install agent\nhelm install patchpulse-agent patchpulse/agent \\\n  --namespace patchpulse \\\n  --set backend.url=http://patchpulse-backend:8000\n```\n\n### Docker Compose (Production)\n\n```bash\ndocker compose -f docker-compose.prod.yml up -d\n```\n\n## 📚 Documentation\n\n- [Architecture](docs/architecture.md) - System design and components\n- [Quick Start](docs/quickstart.md) - Get up and running quickly\n- [Demo Walkthrough](docs/demo.md) - Step-by-step demo scenario\n- [Runbooks](docs/runbooks.md) - Operational guides\n- [Threat Model](docs/threat-model.md) - Security analysis\n\n## 🔐 Security\n\n- API keys never exposed in logs or responses\n- Least-privilege RBAC for agent\n- Encrypted database connections\n- TLS for all API communications\n- Audit logging for all decisions\n- Rate limiting on API endpoints\n\nSee [SECURITY.md](SECURITY.md) for detailed security information.\n\n## 🛠️ Development\n\n### Local Development\n\n```bash\n# Backend\ncd app/backend\npython -m venv venv\nsource venv/bin/activate\npip install -r requirements.txt\nuvicorn main:app --reload\n\n# Agent\ncd app/agent\ngo run cmd/agent/main.go\n\n# Git Integration\ncd app/integrations/git\npython poller.py\n```\n\n### Makefile Commands\n\n```bash\nmake lint          # Run linters\nmake test          # Run tests\nmake docker-up     # Start Docker Compose\nmake docker-down   # Stop Docker Compose\nmake build         # Build Docker images\n```\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests\n5. Submit a pull request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## 📄 License\n\nCopyright © 2026 PatchPulse. All rights reserved.\n\n## 🆘 Support\n\n- Documentation: http://localhost:8000/docs\n- Issues: https://github.com/amarkdotdev/patchpulse/issues\n- Email: support@patchpulse.io\n\n## 🎯 Roadmap\n\n- [ ] Multi-tenant support\n- [ ] Custom guardrail DSL\n- [ ] Integration with more Git providers\n- [ ] Advanced AI models\n- [ ] Compliance reporting\n- [ ] Mobile app\n\n---\n\n**Built with ❤️ by the PatchPulse team**\n"}, "67c01be3094f9e1c8c16b4f23f781ee663f6ce6b": {"t": 1785764252.3960826, "n": 1327, "h": "af74a56773c7d07c", "c": "# PatchPulse\n\nPatchPulse prevents incidents by analyzing infrastructure/app changes and cluster signals, then enforcing pre-flight guardrails with explainable output.\n\n## Quick Start\n\n### Local Development\n\n```bash\n# Start all services\nmake docker-up\n\n# Run tests\nmake test\n\n# View logs\ndocker-compose logs -f\n```\n\n### Kubernetes Deployment\n\n```bash\n# Install via Helm\nmake helm-install\n\n# Uninstall\nmake helm-uninstall\n```\n\n## Architecture\n\nSee [docs/architecture.md](docs/architecture.md) for detailed architecture.\n\n## Components\n\n- **Backend**: FastAPI control plane with policy engine\n- **Agent**: Go-based Kubernetes event collector\n- **Git Integrations**: GitHub and GitLab change detection\n- **Slack Integration**: Risk notifications and approvals\n- **UI**: Minimal web interface for risk reports\n\n## Demo\n\nSee [docs/demo.md](docs/demo.md) for the complete demo scenario.\n\n## Documentation\n\n- [Architecture](docs/architecture.md)\n- [Quickstart](docs/quickstart.md)\n- [Demo](docs/demo.md)\n- [Threat Model](docs/threat-model.md)\n- [Runbooks](docs/runbooks.md)\n- [Assumptions](docs/assumptions.md)\n\n## Development\n\n```bash\nmake lint      # Lint all code\nmake test      # Run all tests\nmake build     # Build all containers\nmake run       # Run backend locally (requires DB)\n```\n\n## License\n\nProprietary - PatchPulse Inc.\n\n"}}}}