Gauntlet

What it is

A green test run can mean the implementation is right, or that the checks were weakened. Gauntlet runs the project’s verification and looks for changes to the verification itself: deleted tests, weakened assertions, new suppressions and protected configuration edits.

A repository policy states the checks, protected paths and review requirements. Gauntlet can report locally and through GitHub. It uses deterministic checks; a model or API key is not needed to judge a change.

Use it with an existing build, test suite and review process. It is a separate command-line tool, not a library your application imports.

Install

Gauntlet is distributed as a CLI release candidate. Get the installer or a platform binary from the official releases; the manual installation instructions explain the alternatives to running the installer script.

You also need the project’s own build and verification tools. Support varies by language pack; check the language support table for your stack.

First check in a repository

After installing the CLI, the GitHub-only path starts in a repository that already has tests:

gauntlet init
gauntlet connect github --protect-only

Review and commit the generated .gauntlet/ and .github/ files, then require the gauntlet check in the default branch’s ruleset. In this mode, the protected tests and configuration come from the base commit and are restored before verification runs.

For the agent-assisted setup, run gauntlet setup and follow the policy discussion in Claude Code. That path begins in shadow mode: it reports without blocking. Agent hooks currently support Claude Code; using Codex to work on this website does not imply that a Codex hook integration exists.

Follow the complete setup guide for the workflow you choose. The regular shadow-mode setup and GitHub-only --protect-only mode have different enforcement behaviour.

What a policy controls

The policy can select verification gates, protect tests and build configuration, set coverage or mutation ratchets, and require owner review for named areas. An existing baseline can allow known findings while flagging new ones.

gauntlet "petshop"
use jvm, typescript
mode shadow
owners @matthewjones372

protect {
  tests    "**/src/test/**"
  fixtures "**/src/test/resources/**", "**/src/testFixtures/**"
  config   "*.gradle.kts", "**/*.gradle.kts", "gradle/**", ".github/workflows/**",
           "web/biome.json", "web/tsconfig.json", "config/detekt/**"
}

Petshop’s complete policy also names its data, contract and domain areas. These are repository rules, not application dependencies. See the policy reference for gate and review semantics.

Where Petshop uses it

Petshop checks both its JVM code and TypeScript front end. Its policy protects tests, fixtures, build files and verification configuration, and marks the database, public contracts and domain code as owned areas.

The checked-in policy uses shadow mode, so it reports rather than enforcing the regular policy. Its GitHub workflow separates the job that executes pull-request code from the job that publishes the decision. The integration notes describe the setup and required branch rules.

Read Petshop’s policy · Read its workflow

Limits and where next

Gauntlet can only judge the checks and evidence available to it. A pass does not prove the application is correct, and detector coverage varies by language and edit. Keep requirements-focused tests and human review.

Local hooks can be disabled unless managed settings enforce them. A GitHub check also needs to be required by the repository’s branch rules to control merging. See the project’s documented trust boundary and detector evidence rather than treating a green result as a security guarantee.