Run Bravos in CI/CD
Bravos gates a change in two places: in the agent’s session, before it opens a
pull request, and in GitHub Actions, on the pull request itself. A nightly
workflow keeps annotating while laptops are closed. These features are Team
features, with a 30-day no-card trial, and each is one flag to bravos setup.
Before you start
Section titled “Before you start”- A repository set up with Bravos.
- A Team licence or trial on this machine. Check with
bravos licence.
The pre-PR gate in the session
Section titled “The pre-PR gate in the session”bravos setup --pre-pr-hookHooks: .claude/settings.json registeredHooks: .codex/hooks.json registeredHooks: .agents/hooks.json registeredpre_pr: .guardlink/config.json lists bravos's gate; run guardlink sync to render it into the agent instruction filesMCP: .mcp.json added codegraph; kept guardlink, cxgMCP: .codex/config.toml added codegraph; kept guardlink, cxgTruncated to the lines about hooks, the gate and MCP. The skill and Cursor
lines before them say nothing changed. The gate registers a hook on the
agent’s gh pr create and gh pr ready. Before the pull request goes out, it
runs the bravos-ship checks: the threat model validates, new claims pass
lint since the merge base, new exposure is disclosed, and no confirmed exploit
sits on a changed path. Run guardlink sync afterwards so the agent
instruction files mention it.
Autopilot
Section titled “Autopilot”bravos setup --autopilotautopilot on: an end-of-turn check (Stop hook) sends the agent back once when changed code lacks annotations, sits under a confirmed or stale claim, or adds exposures; the pre-PR gate checks every gh pr create / gh pr ready.autopilot: the first time proving comes up, the agent asks you once how you want it handled and records your answer in .guardlink/proving.md. BRAVOS_AUTOPILOT=off pauses the check.Truncated to the two autopilot lines. Autopilot turns the pre-PR gate on too.
The PR gate and the nightly in GitHub Actions
Section titled “The PR gate and the nightly in GitHub Actions”bravos setup --ciWorkflows: 3 written, 0 updated, 0 unchanged, 0 skippedTeam view (off): gh variable set BRAVOS_THREAT_ISSUES --body on makes the nightly open an issue for each critical or high threat still untested after 2 days.Truncated to the workflow lines. It writes three files to
.github/workflows/:
| File | Runs | Needs |
|---|---|---|
bravos-pr-gate.yml |
on every pull request | nothing: it runs guardlink only, spends no model and needs no secret |
bravos-nightly-claude.yml |
weekdays at 03:17 UTC, and on demand | BRAVOS_LICENCE and CLAUDE_CODE_OAUTH_TOKEN secrets |
bravos-nightly-codex.yml |
the same schedule, with Codex | BRAVOS_LICENCE and OPENAI_API_KEY secrets |
--workflows picks among pr-gate, nightly-claude, nightly-codex and
nightly-copilot; the Copilot job assigns an annotation task instead of
running an agent in Actions. --schedule takes weekday, daily or
weekly. Commit the files.
Every action in the generated workflows is pinned to a commit, with its
version in a comment beside it. Checkouts use persist-credentials: false,
except Copilot’s setup, which pushes from its checkout. The workflows install
GuardLink and cxg at the versions this Bravos pins, read from the committed
.bravos/hooks/lib/proof-tool-pins.json.
The PR gate
Section titled “The PR gate”The PR gate makes the same rulings as the pre-PR hook. Its steps, from the generated file:
- Threat model parses and resolves:
guardlink validate . - New claims meet the evidence bar: lint since the merge base
- No undisclosed new exposure
- No confirmed exploit on a changed path
- No untested change under a design rule
- Design documents carry no secret or local path
- Changed source to review
- Undefended paths (informational):
guardlink paths --json - SARIF for code scanning:
guardlink sarif . --profile github, then uploaded withgithub/codeql-action/upload-sarif
A gate input that fails or does not parse fails the job as unknown; it never passes. The design-rule step holds a pull request that changes a file a holding rule is enforced in, after that rule was last tested, until its test is replayed or the PR body names the rule. See context from your design documents.
The same gate is published as a reusable action,
Bugb-Technologies/bravos-action
on GitHub Marketplace. It needs no licence and no bravos setup; a team that
only wants the gate adds one step after a full checkout:
- uses: actions/checkout@v4 with: fetch-depth: 0- uses: Bugb-Technologies/bravos-action@v1Its README has the full workflow, including the SARIF upload.
The nightly
Section titled “The nightly”Each night the agent annotates the next slice of unannotated files with
bravos-annotate, the lint gate checks what it wrote, and the job opens one
small pull request. It needs:
- The repository secret
BRAVOS_LICENCE: a CI licence an owner or admin creates for that repository in the account portal. The CLI never renews it. Without it the paid skills say so and stop. - The repository secret
CLAUDE_CODE_OAUTH_TOKENfor the Claude Code nightly on your Claude plan (an existingANTHROPIC_API_KEYremains supported), orOPENAI_API_KEYfor the Codex one. Keep the one you use and delete the other file. - Settings → Actions → General → Allow GitHub Actions to create and approve pull requests.
An optional step replays committed retest kits against a target. It skips
unless vars.BRAVOS_SCAN_TARGET is set and .guardlink/scope.yaml is
committed with a human-written authorization_attestation. It replays kits
only, under the current scheduled proving choice: no probe generation and no
destructive classes. For a disposable loopback build, BRAVOS_APP_START starts
the application. BRAVOS_SCAN_AUTH selects role profiles; provide their session
state privately. The committed proving choice must be schedule for that exact target, and
replay must still run from the current default-branch revision. Kits must be
bound to current claims and tested bytes. Missing target, scope, authorization,
identity or build prerequisites are reported as skips/refusals, not clean coverage. See
authorization and blast radius.
Issues for untested threats
Section titled “Issues for untested threats”The nightly can open one GitHub issue for each critical or high threat that is still untested two days after its annotation was committed. It is off until you turn it on:
gh variable set BRAVOS_THREAT_ISSUES --body onEach issue gives the claim, a link to its line, and how to close it: test it
with bravos-prove, fix it with a @mitigates, or have a named person accept
it. A refuted result, a fix, an acceptance or removing the claim closes it. A
confirmed result keeps it open, relabelled confirmed. At most 10 new issues
open per run. The job runs no agent, needs no secret, and holds only
contents: read and issues: write. BRAVOS_THREAT_ISSUES_DAYS changes the
delay.
Without a licence
Section titled “Without a licence”bravos setup --ci needs a licence — it is on the Team plan: bravos account activate starts a 30-day trial (no card), or https://account.bugb.io/pricingA paid hook on a machine without a licence stands down with one line and never blocks.

