Integration

CI integration

Gate, the composite action, SARIF upload, the pre-commit hook, and the augur → attest trust pipeline.

augur is deterministic and needs no API key, so it slots cleanly into CI and agent loops. Use augur gate to fail a job when a verdict crosses a threshold.

Scope. The shipped composite action installs a prebuilt augur on GitHub-hosted runners (macOS universal or Linux x86_64), so you can drop it into any repo with runs-on: ubuntu-latest or runs-on: macos-latest via uses: CorvidLabs/augur@v0. No Swift toolchain is required. It falls back to building from source only on runners where no prebuilt binary fits (e.g. windows-latest or Linux arm64), which needs Swift on the runner.

The one-liner

workflow step

- run: augur gate --range origin/main..HEAD --threshold block

gate exits 1 when the verdict meets or exceeds the threshold, 0 otherwise (and on no changes). See the CLI reference for exit codes.

The augur gate composite action

This repo ships a composite GitHub Action ("augur gate", action.yml) you can drop into any repo. It installs a prebuilt augur for the runner (macOS universal or Linux x86_64) from the matching release, then runs augur gate against your checkout, no Swift toolchain required. Pin to the moving @v0 tag to track the latest 0.x release, or to an exact tag (e.g. @v0.3.0) to lock a version:

jobs:
  gate:
    runs-on: ubuntu-latest        # or macos-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }   # gate needs history for the range
      - uses: CorvidLabs/augur@v0
        with:
          range: origin/main..HEAD
          threshold: block
          coverage: lcov.info        # optional
          working-directory: .       # optional

The action exposes its result as step outputs:

Prebuilt binaries cover GitHub-hosted macOS and Linux x86_64 runners. Other runners (e.g. windows-latest, Linux arm64) have no prebuilt binary, so the action falls back to building augur from its own source, which needs a Swift toolchain on the runner.

SARIF upload (GitHub code scanning)

augur check --sarif emits SARIF 2.1.0; --sarif-out <path> writes it to a file. Upload it so verdicts surface as code-scanning annotations on the PR:

- run: augur check --range origin/main..HEAD --sarif-out augur.sarif
- uses: github/codeql-action/upload-sarif@v3
  with: { sarif_file: augur.sarif }

augur emits a single rule, augur/change-risk, and one result per assessed file. Each result's level is mapped from its verdict:

The result is regioned on the file's first added line when known. --sarif and --json are mutually exclusive; the output is generated entirely in AugurKit with Foundation Codable (no third-party SARIF dependency) and is deterministic (sorted keys).

GHAS caveat. upload-sarif requires GitHub Advanced Security to be enabled. That is free on public repos but a paid add-on on private repos. On a private repo without GHAS the upload step fails (403). The full examples/workflows/sarif.yml documents this and keeps the gate independent of the upload, so you still get a deterministic pass/fail even where GHAS is off.

Pre-commit hook

examples/hooks/pre-commit runs augur gate --staged --threshold block and refuses the commit on a block verdict (set AUGUR_THRESHOLD=review to also stop on review-grade changes). Install it from the repo root:

ln -s ../../examples/hooks/pre-commit .git/hooks/pre-commit
# or copy it: install -m 0755 examples/hooks/pre-commit .git/hooks/pre-commit
git commit --no-verify   # deliberately bypass for one commit

For agents

verdict=$(augur check --range main..HEAD --json | jq -r .verdict)
[ "$verdict" = "proceed" ] || echo "escalating to a human"

The augur → attest trust pipeline

A verdict from augur is ephemeral: it lives for one CI run and is gone. Its sibling attest makes it durable: attest records who or what reviewed a change, and at what confidence as a signed-or-unsigned provenance note keyed to the commit SHA (stored in git notes), and gates CI / agent loops on a policy. augur scores the risk; attest records the trust. They compose over a pipe and never link to each other:

augur check --json | attest sign --from-augur -        # record the trust
attest verify --policy .attest.json                     # gate on it

attest sign --from-augur - copies augur's verdict and maps its riskScore (0...100) to confidence = 1 − riskScore/100. A worked, end-to-end run is in examples/06-trust-pipeline.sh: an agent attests a review change, a policy demanding human approval for review+ verdicts FAILs, then a human signs off and it PASSes. The policy clears as soon as any human-approved attestation exists on the commit: the human signs off with a plain --human-approved and need not restate the verdict.

Reusable workflow

examples/workflows/trust.yml is a copy-paste GitHub Actions workflow other CorvidLabs repos can adopt. On pull_request it builds augur and runs augur gate --range origin/<base>..HEAD --threshold block, with commented-out steps showing exactly where attest sign / attest verify slot in.