Inputs & troubleshooting

The GitHub Action's inputs, the subcommands, and fixes for the problems people actually hit. Every CLI flag and YAML key, and the JSON schemas, are in the configuration reference.

Action inputs

All optional. Inputs are strings in YAML, so quote numbers and booleans.

Input	Default	What it does
`base-ref`	the PR's base	Branch to diff against.
`advisory`	`false`	Report, never block.
`max-survivors`	`0`	Survivors tolerated before blocking; `0` means any survivor blocks.
`block-on-severity`	unset	Block when a survivor reaches a tier (`low`, `medium`, `high`, `critical`), whatever the count.
`block-on-zero-assertion`	`false`	Also block on tests that assert nothing.
`block-on-pattern`	unset	Gate a pattern lane (`slop`, `security`, `convention`, `docs`, `weakened-tests`, `all`) or a rule id. Comma-separated.
`max-per-function`	`5`	Mutants tested per function — the main cost lever.
`jobs`	`4`	Mutants tested in parallel. Raise on bigger runners.
`timeout`	`60`	Per-mutant test timeout, in seconds.
`test-workspace`	`false`	Run the whole workspace's tests per mutant, not only the changed crate's.
`budget`	unset	Wall-clock limit on the mutation run (`10m`, `600`, `90s`).
`block-on-budget`	`false`	Block when the budget left mutants untested.
`in-place`	`false`	Mutate the checkout so mutants reuse the existing build.
`debt-budget`	unset	Per-PR structural-debt budget: net complexity, duplication and coupling.
`block-on-debt`	`false`	Block when the debt delta exceeds the budget.
`comment`	`true`	Post the pull-request comment, updated in place.
`comment-inline`	`false`	Also post each survivor on its line (GitHub).
`sarif`	unset	Write the findings as SARIF 2.1.0 to this path.
`upload-sarif`	`false`	Upload it to code scanning (needs `security-events: write`).
`config`	unset	Path to a YAML config file; inputs override it.
`metrics-file`	unset	Append a JSON-Lines record of the run, for `slop-gate analyze`.
`version`	`slop-gate-v0.6.1`	Release of the prebuilt binary to install.
`token`	`GITHUB_TOKEN`	Token that posts the comment.

Exit codes

Code	Meaning
`0`	Passed, or ran advisory.
`2`	Blocked by a threshold you set. The report says which.
`1`	Operational failure. Never a verdict about your code.

Subcommands

slop-gate estimate — how many mutants a diff produces, without building (--json for CI).
slop-gate merge-reports — one verdict and one comment from sharded runs.
slop-gate analyze --metrics-file runs.jsonl — block rate, fix-vs-override, latency and the mutation-score trend across recorded runs.
slop-gate progression — render a repository's milestone plan against its own commits and pull requests.

Troubleshooting

Exit 2 — surviving mutations exceed the allowed count

The real signal: your suite passed over mutations of the lines you changed. Add the assertion the survivor points at (file, line and the exact mutation are listed), or raise max-survivors on purpose.

Exit 2 — the test suite was not green & stable

The pre-flight found the suite red or flaky, so survivors could not be trusted. Fix the red test. For a flaky one, --preflight-runs 2 catches the flip before any mutant runs.

Exit 1 — no merge-base, or a diff error

A shallow checkout: the base ref is not reachable. Check out with fetch-depth: 0. Outside pull-request events, set base-ref.

Exit 1 — `cargo-mutants` not found

cargo install cargo-mutants. The Action and the image already include it.

Exit 1 — mutants accounted for fewer than expected

The engine died part-way, usually from the Windows temp-path limit. Run on Linux, or in the Docker image.

Warning — could not post the PR comment

The token lacks pull-requests: write, or the run is not tied to a pull request. The verdict is unaffected.

Runs are too slow

Compiling and testing each mutant dominates. In order: cache the build (rust-cache + in-place), lower max-per-function, set a budget, then shard. Use slop-gate estimate to see the mutant count first.

Timed-out mutants

If your normal suite runs near the limit, raise timeout. Otherwise it is the engine correctly stopping a mutant that loops forever.

More symptoms, with causes and fixes, are in the operations guide.