checkov --soft-fail: Report Without Failing CI
checkov --soft-fail forces a zero exit code so findings still print but the pipeline does not fail on them.
When you first add Checkov to a repo full of existing infrastructure, hard-failing every PR is unworkable. Soft-fail lets you surface findings while you triage, then tighten later.
What it does
By default checkov exits 1 when any check fails. --soft-fail makes it always exit 0 regardless of findings, so the report appears but the step succeeds. --soft-fail-on lets you soft-fail only specific checks while still hard-failing the rest, and --hard-fail-on does the inverse.
Common usage
# report everything, never fail the build
checkov -d . --soft-fail
# only these checks are non-blocking; others still fail
checkov -d . --soft-fail-on CKV_AWS_18,CKV_AWS_21
# fail only on a critical subset
checkov -d . --hard-fail-on CKV_AWS_20Options
| Flag | What it does |
|---|---|
| --soft-fail | Always exit 0 regardless of findings |
| --soft-fail-on <ids> | Make only these checks non-blocking |
| --hard-fail-on <ids> | Fail the build only on these checks |
| --compact | Trim output while triaging |
In CI
A common rollout: start with --soft-fail so PRs are not blocked, watch the findings for a sprint, then switch to --hard-fail-on for a curated critical set, and finally drop soft-fail entirely once the backlog is clean. This avoids the all-or-nothing wall that makes teams disable the tool.
Common errors in CI
The step "passing" while the report shows failed checks is exactly what --soft-fail does, not a bug. If --soft-fail-on does not change the exit code, the IDs may not match any finding. Combining --soft-fail with --hard-fail-on is contradictory; pick one strategy, since precedence between them is easy to get wrong.