Feature: GitHub Webhooks Integration

[flemzord]

Feature: GitHub Webhooks Integration

Summary

Enable the compliance CLI to act as a webhook receiver, automatically triggering compliance checks when specific GitHub events occur (push, PR creation, settings changes, etc.).

Problem Statement

Currently, compliance checks must be triggered manually or via scheduled CI/CD. This reactive approach means violations can exist between check intervals. By integrating with GitHub webhooks, we can immediately validate compliance when relevant changes occur.

Proposed Solution

Implement a webhook server mode that receives GitHub events and triggers targeted compliance checks based on the event type and affected resources.

Detailed Design

Command Line Interface

# Start webhook server
github-compliance-cli webhook-server --config compliance.yml --token $TOKEN --port 8080

# With HTTPS/TLS
github-compliance-cli webhook-server --config compliance.yml --token $TOKEN --port 443 --tls-cert cert.pem --tls-key key.pem

# With webhook secret validation
github-compliance-cli webhook-server --config compliance.yml --token $TOKEN --webhook-secret $WEBHOOK_SECRET

# Register webhooks automatically
github-compliance-cli webhook-register --config compliance.yml --token $TOKEN --webhook-url https://compliance.company.com/webhook

Configuration Schema

webhooks:
  enabled: true
  server:
    port: 8080
    host: "0.0.0.0"
    path: "/webhook"
    secret: "${WEBHOOK_SECRET}"  # For signature validation
    tls:
      enabled: true
      cert_file: "/etc/ssl/cert.pem"
      key_file: "/etc/ssl/key.pem"

  # Event subscriptions
  events:
    # Repository settings changes
    repository:
      enabled: true
      triggers: ["created", "edited", "archived", "unarchived", "publicized", "privatized"]
      checks: ["repository-settings", "team-permissions"]

    # Branch protection changes
    branch_protection_rule:
      enabled: true
      triggers: ["created", "edited", "deleted"]
      checks: ["branch-protection"]

    # Team and permission changes
    team_add:
      enabled: true
      checks: ["team-permissions"]

    member:
      enabled: true
      triggers: ["added", "removed", "edited"]
      checks: ["team-permissions"]

    # Push events (for commit signing)
    push:
      enabled: true
      branches: ["main", "master", "release/*"]
      checks: ["commit-signing"]

    # Security events
    security_advisory:
      enabled: true
      checks: ["security-scanning"]

    dependabot_alert:
      enabled: true
      checks: ["security-scanning"]

  # Response behavior
  response:
    async: true  # Return immediately, process in background
    timeout_seconds: 30
    retry_attempts: 3

  # Check execution
  execution:
    mode: "targeted"  # targeted (only affected repo) or full (all repos)
    debounce_seconds: 10  # Prevent duplicate checks for rapid events
    queue:
      max_size: 1000
      process_concurrency: 5

  # Reporting
  reporting:
    github_checks: true  # Create GitHub check runs
    github_issues: true  # Create issues for violations
    pull_request_comments: true  # Comment on PRs with violations

Architecture

Core Components

class WebhookServer {
  private server: Express.Application;
  private queue: EventQueue;
  private processor: EventProcessor;
  private validator: WebhookValidator;

  async start(): Promise<void>;
  async stop(): Promise<void>;
  private handleWebhook(req: Request, res: Response): Promise<void>;
  private validateSignature(payload: string, signature: string): boolean;
}

interface EventProcessor {
  process(event: GitHubEvent): Promise<CheckResult[]>;
  determineChecks(event: GitHubEvent): string[];
  executeChecks(repo: string, checks: string[]): Promise<CheckResult[]>;
}

interface EventQueue {
  push(event: GitHubEvent): Promise<void>;
  pop(): Promise<GitHubEvent | null>;
  size(): number;
  clear(): Promise<void>;
}

class WebhookValidator {
  verifySignature(payload: string, signature: string, secret: string): boolean;
  validateEvent(event: any): GitHubEvent;
  isRelevantEvent(event: GitHubEvent): boolean;
}

Event Processing Flow

1. Receive Webhook

   • Validate X-Hub-Signature-256 header
   • Parse JSON payload
   • Validate event structure

2. Filter Events

   • Check if event type is configured
   • Verify repository/organization match
   • Apply custom filters

3. Queue Processing

   • Add to processing queue
   • Debounce rapid events
   • Respect concurrency limits

4. Execute Checks

   • Determine relevant checks based on event
   • Run checks on affected repository
   • Generate compliance report

5. Report Results

   • Create GitHub check run
   • Comment on PR if applicable
   • Create/update issues
   • Send alerts if configured

GitHub Integration Features

1. GitHub Check Runs

interface CheckRunIntegration {
  createCheckRun(repo: string, sha: string): Promise<CheckRun>;
  updateCheckRun(id: number, status: CheckStatus): Promise<void>;
  addAnnotations(id: number, violations: Violation[]): Promise<void>;
}

2. Pull Request Integration

• Comment with compliance summary
• Block merge if violations exist
• Suggest fixes in PR comments
• Auto-approve if compliant

3. Issue Management

• Create issues for violations
• Auto-close when resolved
• Link issues to PRs
• Track resolution time

User Stories

• As a developer, I want immediate feedback when my PR violates compliance rules
• As a security engineer, I want alerts when branch protection is weakened
• As a platform engineer, I want automated checks when new repositories are created
• As a team lead, I want PR blocks when commit signing requirements aren't met

Technical Considerations

Security

• Webhook secret validation (HMAC-SHA256)
• TLS/HTTPS for production deployment
• Rate limiting to prevent DoS
• IP allowlisting for GitHub webhooks

Reliability

• Persistent queue for event processing
• Graceful shutdown with queue draining
• Health check endpoint
• Automatic webhook re-registration

Performance

• Async processing with worker pool
• Event debouncing and deduplication
• Efficient queue management
• Caching for frequently accessed data

Testing Strategy

• Unit tests for signature validation
• Integration tests with mock GitHub events
• Load testing with high event volumes
• End-to-end tests for complete workflow
• Security testing for webhook validation

Deployment Considerations

# Docker deployment
version: '3.8'
services:
  compliance-webhook:
    image: github-compliance-cli:latest
    command: webhook-server
    ports:
      - "8080:8080"
    environment:
      - GITHUB_TOKEN=${GITHUB_TOKEN}
      - WEBHOOK_SECRET=${WEBHOOK_SECRET}
    volumes:
      - ./compliance.yml:/config/compliance.yml
      - webhook-state:/var/lib/compliance

# Kubernetes deployment
apiVersion: apps/v1
kind: Deployment
metadata:
  name: compliance-webhook
spec:
  replicas: 3
  template:
    spec:
      containers:
      - name: webhook-server
        image: github-compliance-cli:latest
        args: ["webhook-server"]

Documentation Needs

• Webhook setup guide for GitHub organizations
• Security best practices for webhook deployment
• Troubleshooting guide for common webhook issues
• Integration guide with CI/CD systems
• Event type reference and check mapping

Success Criteria

• Webhook signature validation works correctly
• Events trigger appropriate compliance checks
• Processing completes within 30 seconds
• GitHub check runs display correctly
• PR integration provides actionable feedback
• Queue handles 1000+ events without loss
• System remains stable under load

Dependencies

• Web framework (Express/Fastify)
• Queue implementation (Bull/BullMQ)
• GitHub Apps or OAuth App registration
• TLS certificates for production

Open Questions

1. Should we support GitHub Apps in addition to webhooks?
2. How to handle webhook delivery failures?
3. Should we provide a UI for webhook management?
4. How to scale horizontally for large organizations?
5. Should we support webhook replay for debugging?

Future Enhancements

• GitHub App implementation for better permissions
• Webhook event replay and debugging UI
• Custom event handlers via plugins
• Integration with GitHub Actions
• Webhook metrics and analytics dashboard
• Support for other Git providers (GitLab, Bitbucket)