Skip to content

Run in CI

This GitHub Actions workflow checks the repository on every pull request and push. Before you add it, commit sprawl-guard.toml and, if you created one, sprawl-guard.ratchet.toml. Replace <VERSION> with a release so that a new release can’t change the result of your CI without a commit.

Pin the version in package.json first, and commit the updated lockfile:

Terminal window
pnpm add --save-dev --save-exact @kpozin/sprawl-guard@<VERSION>

pnpm/action-setup installs the pnpm version that the packageManager field in package.json names. If the project doesn’t set that field, give the action a version input instead.

.github/workflows/sprawl-guard.yml
name: Sprawl Guard
on: [pull_request, push]
permissions:
contents: read
jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: pnpm/action-setup@v6
- uses: actions/setup-node@v7
with:
node-version: 22
- run: pnpm install --frozen-lockfile
- run: pnpm exec sprawl-guard config upgrade --check
- run: pnpm exec sprawl-guard check --format github

The workflow runs two commands:

  • sprawl-guard config upgrade --check fails when the configuration file uses an older format. After you update Sprawl Guard, run sprawl-guard config upgrade --write locally and commit the result.
  • sprawl-guard check --format github checks the whole repository and annotates each violation on the workflow run. The pull request’s diff also shows the annotation for a file whose first line is part of the diff. The step still fails when the check finds violations. Don’t pass it paths in CI, because a check on selected paths can miss violations elsewhere.

Pass --format github in the workflow rather than setting [output].format, so that local checks keep plain output.

CI never changes the ratchet file. Record improvements locally, as described in Work with the ratchet, and commit them.

To catch failures before CI does, run sprawl-guard check in a Git pre-commit hook. For example, with the pre-commit framework:

The hook runs the version in node_modules that the lockfile pins, so install the project’s dependencies first.

.pre-commit-config.yaml
repos:
- repo: local
hooks:
- id: sprawl-guard
name: Sprawl Guard
entry: pnpm exec sprawl-guard check
language: system
always_run: true
pass_filenames: false

pass_filenames: false makes the hook check the whole repository instead of only the changed files, and always_run: true runs it on commits that only delete files.

For code-scanning tools, use sprawl-guard check --format sarif. For your own scripts, use --format json. Read the exit code before you parse the output: 0 means the check passed, 1 means it found violations, and 2 means gaps in the analysis failed the check (under the default unreadable_paths = "fail") or it hit an error. An error other than a gap in the analysis leaves the output empty. See CLI and output for the formats.

© 2026 Konstantin Pozin