From 67fdebff77c74d39acd7598dbca81c9d2836a990 Mon Sep 17 00:00:00 2001 From: William Woodruff Date: Sat, 29 Mar 2025 01:23:52 +0200 Subject: [PATCH] docs: add a callout about SARIF exit code behavior (#630) Signed-off-by: William Woodruff --- docs/usage.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/usage.md b/docs/usage.md index e97ef2e2..9b60e1f3 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -455,6 +455,21 @@ jobs: For more inspiration, see `zizmor`'s own [repository workflow scan], as well as GitHub's example of [running ESLint] as a security workflow. +!!! important + + When using `--format sarif`, `zizmor` does not use its + [exit codes](#exit-codes) to signal the presence of findings. As a result, + `zizmor` will always exit with code `0` even if findings are present, + **unless** an internal error occurs during the audit. + + As a result of this, the `zizmor.yml` workflow itself will always + succeed, resulting in a green checkmark in GitHub Actions. + This should **not** be confused with a lack of findings. + + To prevent a branch from being merged with findings present, you can + use GitHub's rulesets feature. For more information, see + [About code scanning alerts - Pull request check failures for code scanning alerts]. + [zizmor package from PyPI]: https://pypi.org/p/zizmor [SARIF]: https://sarifweb.azurewebsites.net/ @@ -467,6 +482,8 @@ as GitHub's example of [running ESLint] as a security workflow. [Advanced Security]: https://docs.github.com/en/get-started/learning-about-github/about-github-advanced-security +[About code scanning alerts - Pull request check failures for code scanning alerts]: https://docs.github.com/en/code-security/code-scanning/managing-code-scanning-alerts/about-code-scanning-alerts#pull-request-check-failures-for-code-scanning-alerts + ### Use with GitHub Enterprise `zizmor` supports GitHub instances other than `github.com`.