GitHub App
Install the App on a repo or org, configure the manifest, and every pull_request event triggers a PR Diff Red-Team Gate. The complement to the CLI/Action flow.
The GitHub App is the zero-config path to the PR Diff Red-Team Gate: install once at the org level, configure the manifest, and every pull_request event on watched files triggers a scan with results posted back to the merge box.
It is the complement to the CLI/Action flow — same manifest schema, different ownership model. This page helps you pick, and states exactly what ships today.
Key points
- Webhook authenticated by X-Hub-Signature-256 HMAC against GITHUB_APP_WEBHOOK_SECRET. JWT/API-key auth bypassed for this route only.
- Listens to pull_request events; runs the gate (manifest → scan → Check Run + comment) in a detached background task to ACK within ~10s.
- Installation token minted per-org via the App's private key. Stored in githubInstallStore so subsequent events do not re-handshake.
- Verdict (PROMOTE / HOLD) posts as a Check Run + sticky PR comment so the gate is visible in the merge box.
App vs. CLI/Action
- Use the App when you want zero-config gating across many repos — install once at the org level.
- Use the Action/CLI when the team prefers an explicit workflow file and per-repo opt-in.
- The App is the only path to native Check Runs (the API surface for the merge box red/green).
Choose the App when many repos should be gated without each team maintaining a workflow file; choose Action/CLI when per-repo opt-in and an explicit workflow file are the team's preference. Native Check Runs — the red/green in the merge box — are the App's distinguishing surface.
What ships today
- Install handshake, webhook receiver, signature verification, manifest discovery, Check Run + comment posting.
- Manifest schema mirrors .doesitdefend.yml from the Action — target.endpoint, template, watched paths.
- Installation state persisted; reinstalls cleanly handle revoke + re-grant cycles.
What ships today: the install handshake, the webhook receiver with signature verification, manifest discovery mirroring the Action's .doesitdefend.yml, and persisted installation state that handles revoke and re-grant cycles cleanly.
Related resources