Skip to content

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.

  • A repository set up with Bravos.
  • A Team licence or trial on this machine. Check with bravos licence.
Terminal window
bravos setup --pre-pr-hook
Hooks: .claude/settings.json registered
Hooks: .codex/hooks.json registered
Hooks: .agents/hooks.json registered
pre_pr: .guardlink/config.json lists bravos's gate; run guardlink sync to render it into the agent instruction files
MCP: .mcp.json added codegraph; kept guardlink, cxg
MCP: .codex/config.toml added codegraph; kept guardlink, cxg

Truncated 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.

Terminal window
bravos setup --autopilot
autopilot 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”
Terminal window
bravos setup --ci
Workflows: 3 written, 0 updated, 0 unchanged, 0 skipped
Team 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 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 with github/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@v1

Its README has the full workflow, including the SARIF upload.

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:

  1. 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.
  2. The repository secret CLAUDE_CODE_OAUTH_TOKEN for the Claude Code nightly on your Claude plan (an existing ANTHROPIC_API_KEY remains supported), or OPENAI_API_KEY for the Codex one. Keep the one you use and delete the other file.
  3. 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.

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:

Terminal window
gh variable set BRAVOS_THREAT_ISSUES --body on

Each 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.

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/pricing

A paid hook on a machine without a licence stands down with one line and never blocks.