checkov --compact and Hard-Fail Threshold in CI
checkov scans infrastructure-as-code and exits 1 when any check fails; --hard-fail-on and --soft-fail-on tune exactly which severities or check ids break the build.
Checkov lints Terraform, CloudFormation, Kubernetes, and more for misconfigurations. The interesting CI knobs are the exit-code controls that decide what counts as a build-breaking failure.
What it does
checkov -d . runs policy checks and exits 1 if any fails, 0 if all pass. --hard-fail-on names severities or check ids that must fail the build, --soft-fail-on names ones that report but do not, and --soft-fail makes the whole run advisory (always exit 0).
Common usage
checkov -d . --compact --quiet
# only hard-fail on HIGH and CRITICAL severities
checkov -d . --hard-fail-on HIGH,CRITICAL --soft-fail
# fail only on specific checks
checkov -d . --hard-fail-on CKV_AWS_20Options
| Flag | What it does |
|---|---|
| -d <dir> | Directory of IaC to scan |
| --hard-fail-on <list> | Severities or check ids that fail the build |
| --soft-fail-on <list> | Checks that report but do not fail |
| --soft-fail | Always exit 0 (advisory mode) |
| --compact | Hide the code block for each finding |
| --quiet | Show only failed checks |
| -o, --output <fmt> | cli, json, sarif, junitxml, github_failed_only |
In CI
checkov already exits 1 on a failed check, so the gate works out of the box; layer --soft-fail plus --hard-fail-on HIGH,CRITICAL to break the build only on serious severities while still reporting the rest. Use --compact --quiet to keep logs readable.
Common errors in CI
"No checks were performed" usually means -d pointed at a directory with no recognized IaC. A pipeline that never fails despite findings has --soft-fail set globally. "Choose either --hard-fail-on or --soft-fail-on" type confusion arises when overlapping ids land in both lists; keep them disjoint.