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:
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.
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 githubPin the version in package.json first, and commit the updated lockfile:
npm install --save-dev --save-exact @kpozin/sprawl-guard@<VERSION>name: Sprawl Guard
on: [pull_request, push]
permissions: contents: read
jobs: check: runs-on: ubuntu-latest steps: - uses: actions/checkout@v7 - uses: actions/setup-node@v7 with: node-version: 22 - run: npm ci - run: node_modules/.bin/sprawl-guard config upgrade --check - run: node_modules/.bin/sprawl-guard check --format githubPin the version in pyproject.toml first, and commit the updated uv.lock:
uv add --dev sprawl-guard==<VERSION>name: Sprawl Guard
on: [pull_request, push]
permissions: contents: read
jobs: check: runs-on: ubuntu-latest steps: - uses: actions/checkout@v7 - uses: astral-sh/setup-uv@v10 - run: uv run --locked sprawl-guard config upgrade --check - run: uv run --locked sprawl-guard check --format githubThe workflow downloads the prebuilt binary for <VERSION> from its GitHub release, so it needs no
Rust toolchain or build. Before it runs the binary, gh attestation verify confirms that Sprawl
Guard’s release workflow built the archive from that version’s tag. If it didn’t, the install step
fails and the check doesn’t run.
name: Sprawl Guard
on: [pull_request, push]
permissions: contents: read
jobs: check: runs-on: ubuntu-latest steps: - uses: actions/checkout@v7 - name: Install Sprawl Guard env: GH_TOKEN: ${{ github.token }} VERSION: <VERSION> run: | archive="sprawl-guard-${VERSION}-x86_64-unknown-linux-gnu.tar.gz" install_dir="${RUNNER_TEMP}/sprawl-guard" mkdir "${install_dir}" gh release download "v${VERSION}" --repo kpozin/sprawl-guard \ --pattern "${archive}" --dir "${install_dir}" gh attestation verify "${install_dir}/${archive}" --repo kpozin/sprawl-guard \ --signer-workflow kpozin/sprawl-guard/.github/workflows/release.yml \ --source-ref "refs/tags/v${VERSION}" tar -xzf "${install_dir}/${archive}" -C "${install_dir}" echo "${install_dir}" >> "${GITHUB_PATH}" - run: sprawl-guard config upgrade --check - run: sprawl-guard check --format githubOn a macOS or Arm Linux runner, replace x86_64-unknown-linux-gnu with the target of the matching
archive on the release page.
The workflow runs two commands:
sprawl-guard config upgrade --checkfails when the configuration file uses an older format. After you update Sprawl Guard, runsprawl-guard config upgrade --writelocally and commit the result.sprawl-guard check --format githubchecks 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.
Run the check before you commit
Section titled “Run the check before you commit”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.
repos: - repo: local hooks: - id: sprawl-guard name: Sprawl Guard entry: pnpm exec sprawl-guard check language: system always_run: true pass_filenames: falseAdd a script to package.json that runs the check:
{ "scripts": { "sprawl-guard:check": "sprawl-guard check" }}The script runs the version in node_modules that the lockfile pins, so install the project’s
dependencies first.
repos: - repo: local hooks: - id: sprawl-guard name: Sprawl Guard entry: npm run --silent sprawl-guard:check language: system always_run: true pass_filenames: falsepre-commit installs the version that additional_dependencies names into the hook’s own
environment, so every developer runs that version. Name the version that the CI workflow pins,
and change both together.
repos: - repo: local hooks: - id: sprawl-guard name: Sprawl Guard entry: sprawl-guard check language: python additional_dependencies: ["sprawl-guard==<VERSION>"] always_run: true pass_filenames: falseThe hook runs whichever sprawl-guard is on your PATH, so install the version that the CI workflow pins:
cargo install sprawl-guard --version <VERSION> --lockedWhen you change the version in CI, run the command again with the new version. To see which
version you have, run sprawl-guard --version.
repos: - repo: local hooks: - id: sprawl-guard name: Sprawl Guard entry: sprawl-guard check language: system always_run: true pass_filenames: falsepass_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.
Use the results in other tools
Section titled “Use the results in other tools”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.