GitHub App: one-click install for any repo (distribution / virality)

[peaktwilight]

Motivation

Right now the friction to try foxguard on CI is:

1. Read the README
2. Copy the GitHub Actions YAML into .github/workflows/foxguard.yml
3. Commit, push, wait for CI, hope the YAML renders correctly
4. Repeat per repo

That's 5+ minutes per repo and gets worse at org scale. A GitHub App changes this to:

1. Click "Install"
2. Pick repos
3. Done — foxguard runs on every PR automatically

This is the friction curve that makes tools go viral: time-to-first-scan drops from 5 minutes to 30 seconds. Dependabot, CodeRabbit, Greptile, Coderabbit, Snyk — all the tools that spread organically are GitHub Apps.

Scope

Phase 1 — minimum viable App:

• GitHub App registration (org-owned under PwnKit-Labs)
• Install flow: user clicks "Install", grants repo access, sees welcome comment
• On pull_request event: run foxguard on changed files, post a comment with findings (reuse existing --github-pr output path)
• Zero config — works out of the box with defaults
• Respect .foxguard.yml if present

Phase 2 — polish:

• Check Runs API instead of (or alongside) comments — inline annotations on the diff
• Status checks (block merge on new critical/high findings — opt-in)
• Badge endpoint: shields.io/endpoint?url=... returning "foxguard: clean" / "foxguard: N issues"

Phase 3 — monetization / org:

• Per-org dashboard showing history, trends, triage
• Baseline management
• Team-level config

Technical approach

• Webhook receiver: Rust (actix-web or axum)
• Hosting: Fly.io or Railway (free tier covers hobby scale). Self-hostable by design — publish a Docker image, let orgs run their own if they want.
• Auth: GitHub App JWT flow, stateless beyond install metadata
• Scan execution: same foxguard binary we already ship, invoked on the cloned PR diff in a sandboxed temp dir with a scan timeout
• Resource limits: 60s scan cap, 1GB repo cap to start; fail-soft on timeout (post a comment saying "scan skipped — repo too large, run locally with `npx foxguard .`")

Distribution

• Marketplace listing (free tier for OSS, paid for private repos if we ever monetize)
• Landing page at foxguard.dev/github with install CTA
• "Install GitHub App" button in README (right next to npx foxguard .)

Non-goals

• Replacing the CLI — the App is a distribution surface, not the core product
• Hosted rule management (users still put .foxguard.yml in their repo)
• Auth beyond GitHub (no separate foxguard accounts for phase 1)

Why it makes sense now

• foxguard scan is already fast enough to run in a PR webhook handler (most repos scan in <1s)
• --github-pr output format already exists — the hardest part (nice PR comments) is done
• PQ crypto arc just landed (feat: post-quantum vulnerable crypto detection rules #217–CNSA 2.0 compliance module via rule metadata (closes #241) #245) — there's a marketing narrative to ride ("Is your codebase CNSA 2.0 ready? Install the app and find out in 30 seconds")
• Dependabot/CodeRabbit/Greptile have proven the App distribution model works for security tools

Open questions

• Org structure: App owned by PwnKit-Labs org, or a separate app-specific org?
• Public webhook host vs self-hostable? (I'd argue publish a reference Docker image so orgs with air-gapped CI can self-host, and run a public instance for everyone else)
• Trial/free tier boundaries if we ever monetize

Happy to scope down further if phase 1 is still too broad.