Guides

Gate merges

Run the Kelvar scanner in CI and fail the job when a pull request introduces a high or critical finding. The scanner is deterministic, needs no model and no network, and exits non-zero when it blocks.

#How blocking works

scan prints a JSON report and sets the exit status.

The built-in codebase-guardian agent blocks. Its checks are secrets, deps, iac and zero_click. See Scanner checks.

#GitHub Actions

Check out your code, make the scanner available, and run it on the whole tree. The job fails when the scanner exits with status 1.

name: kelvar
on: pull_request

jobs:
  scan:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v4
      - name: Scan
        run: PYTHONPATH="$KELVAR_PYTHON_PATH" python3 -m vigil.cli scan . > kelvar-report.json
      - name: Upload report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: kelvar-report
          path: kelvar-report.json

Set KELVAR_PYTHON_PATH to the folder that holds the vigil package in your Kelvar install. Upload the report with if: always() so it is available when the job fails.

#Pre-commit hook

To catch issues before they are committed, scan your working changes with --diff. Save this as .git/hooks/pre-commit and make it executable.

#!/bin/sh
PYTHONPATH=/path/to/kelvar/python python3 -m vigil.cli scan . --diff >/dev/null || {
  echo "Kelvar blocked this commit. Run the scan to see findings."
  exit 1
}

#Tuning what blocks

Add a repository agent in .vigil/agent.json to scope checks to paths. A repository agent runs in addition to the built-in agent. To make a check advisory in one area, scope it and set on_finding to report.

{
  "name": "docs-only",
  "permissions": { "paths": ["docs/**"] },
  "checks": ["secrets"],
  "on_finding": "report"
}

See Configuration for the full schema.

#Reading the result

The report lists each finding with check, severity, path, line and message. Use jq to extract what you need.

jq -r '.findings[] | select(.severity=="critical") | "\(.path):\(.line) \(.message)"' kelvar-report.json

#Beyond the scanner

The scanner catches known patterns. The agents go further, reading code and manifests to confirm whether an issue is real. For pull requests, connect GitHub so that agents audit the repositories you gate.