# Run in CI

Check the whole repository on every pull request and push.

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](https://github.com/kpozin/sprawl-guard/releases) so that a new
release can't change the result of your CI without a commit.

**pnpm**

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

```sh
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.

```yaml title=".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
```

**npm**

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

```sh
npm install --save-dev --save-exact @kpozin/sprawl-guard@<VERSION>
```

```yaml title=".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: 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 github
```

**uv**

Pin the version in `pyproject.toml` first, and commit the updated `uv.lock`:

```sh
uv add --dev sprawl-guard==<VERSION>
```

```yaml title=".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: astral-sh/setup-uv@v10
      - run: uv run --locked sprawl-guard config upgrade --check
      - run: uv run --locked sprawl-guard check --format github
```

**Cargo**

The 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.

```yaml title=".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
      - 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 github
```

On 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 --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](/sprawl-guard/ratchet.md), and commit them.

## 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](https://pre-commit.com/) framework:

**pnpm**

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

```yaml title=".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
```

**npm**

Add a script to `package.json` that runs the check:

```json title="package.json"
{
  "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.

```yaml title=".pre-commit-config.yaml"
repos:
  - repo: local
    hooks:
      - id: sprawl-guard
        name: Sprawl Guard
        entry: npm run --silent sprawl-guard:check
        language: system
        always_run: true
        pass_filenames: false
```

**uv**

pre-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.

```yaml title=".pre-commit-config.yaml"
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: false
```

**Cargo**

The hook runs whichever `sprawl-guard` is on your `PATH`, so install the version that the CI workflow pins:

```sh
cargo install sprawl-guard --version <VERSION> --locked
```

When you change the version in CI, run the command again with the new version. To see which
version you have, run `sprawl-guard --version`.

```yaml title=".pre-commit-config.yaml"
repos:
  - repo: local
    hooks:
      - id: sprawl-guard
        name: Sprawl Guard
        entry: 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.

## 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](/sprawl-guard/reference/cli-and-output.md#output-formats) for
the formats.
