Quickstart
The 30-minute path from zero to a Surety Pass on a real PR. This page describes the spec for the experience the GitHub App and CLI ship in shadow mode.
Prerequisites
- A GitHub repository you can install apps on
- One open or recent PR you can label
- Optional: Docker installed locally if you want to validate the evidence pack offline
1 · Install the Surety GitHub App
Install the app on the repository (or org). Surety asks for the minimum permissions needed to read PR metadata and write Check Runs and PR comments.
2 · Drop in surety.policy.yaml
Add a policy file at the repository root. A minimal starting point:
version: 0
mode: shadow
risk_tiers:
default: medium
executors:
allowed: [claude-code, codex, copilot, cursor, openhands, manual]
runtime:
default: docker
gates:
medium:
required: [typecheck, tests, secrets, dependency_vulns]
3 · Trigger Surety Pass
Either label any PR surety:evidence or comment /surety evidence. Surety runs in shadow mode — never blocks merge.
4 · Read the verdict
Within a few minutes, Surety publishes a Check Run titled Surety Pass and a PR comment with the verdict, gate breakdown, agent provenance, and a link to the signed evidence pack.
Shadow mode is non-blocking by design. Most teams stay in shadow for 4–6 weeks, graduate to advisory, and only enable required mode once the gate set is tuned.