Skip to content

Quickstart🔗

First, run zizmor -h to make sure your installation succeeded.

You should see something like this:

Static analysis for GitHub Actions

Usage: zizmor [OPTIONS] <INPUT>...

Input Options:
  <INPUT>...               The inputs to audit
      --collect <KIND>...  Control which kinds of inputs are collected for auditing [default: default] [possible values: all, default, workflows, actions, dependabot, pre-commit]
      --strict-collection  Fail instead of warning on syntax and schema errors in collected inputs

Audit Options:
      --fix[=<MODE>]            Fix findings automatically, when available (EXPERIMENTAL) [possible values: safe, unsafe-only, all]
  -p, --pedantic                Emit 'pedantic' findings
      --persona <PERSONA>       The persona to use while auditing [default: regular] [possible values: auditor, pedantic, regular]
      --min-severity <LEVEL>    Filter all results below this severity [possible values: informational, low, medium, high]
      --min-confidence <LEVEL>  Filter all results below this confidence [possible values: low, medium, high]
      --no-ignores              Don't honor ignore comments or ignore rules in configuration

Output Options:
  -v, --verbose...              Increase logging verbosity
  -q, --quiet...                Decrease logging verbosity
      --format <KIND>           The output format to emit. By default, cargo-style diagnostics will be emitted [default: plain] [possible values: plain, json, json-v1, sarif, github]
      --no-progress             Don't show progress bars, even if the terminal supports them
      --color <WHEN>            Control the use of color in output [possible values: auto, always, never]
      --render-links <WHEN>     Whether to render OSC 8 links in the output [env: ZIZMOR_RENDER_LINKS=] [default: auto] [possible values: auto, always, never]
      --show-audit-urls <WHEN>  Whether to render audit URLs in the output, separately from any URLs embedded in OSC 8 links [env: ZIZMOR_SHOW_AUDIT_URLS=] [default: auto] [possible values: auto, always, never]
      --no-exit-codes           Disable all error codes besides success and tool failure

Network Options:
  -o, --offline                    Perform only offline operations [env: ZIZMOR_OFFLINE=]
      --gh-token <GH_TOKEN>        The GitHub API token to use [env: GH_TOKEN or GITHUB_TOKEN or ZIZMOR_GITHUB_TOKEN]
      --gh-hostname <GH_HOSTNAME>  The GitHub Server Hostname. Defaults to github.com [env: GH_HOST=] [default: github.com]
      --no-online-audits           Perform only offline audits [env: ZIZMOR_NO_ONLINE_AUDITS=]
      --cache-dir <DIR>            The directory to use for HTTP caching. By default, a host-appropriate user-caching directory will be used

Options:
      --lsp                  Run in language server mode (EXPERIMENTAL)
  -c, --config <FILE>        The configuration file to load. This loads a single configuration file across all input groups, which may not be what you intend [env: ZIZMOR_CONFIG=]
      --no-config            Disable all configuration loading
      --completions <SHELL>  Generate tab completion scripts for the specified shell [possible values: bash, elvish, fish, nushell, powershell, zsh]
      --thanks               Emit thank-you messages for zizmor's sponsors
  -h, --help                 Print help (see more with '--help')
  -V, --version              Print version

Tip

Run zizmor --help for a longer and more detailed version of zizmor -h.

Running zizmor🔗

Here are some different ways you can run zizmor locally:

You can run zizmor on one or more individual files:

zizmor ci.yml tests.yml lint.yml action.yml

These can be in any directory as well:

zizmor ./subdir/ci.yml ../sibling/tests.yml ./action/action.yml

Tip

Pass --collect=workflows to avoid collecting anything except workflow definitions.

When given one or more local directories, zizmor will treat each as a repository and attempt to workflows and other auditable inputs within it.

# repo-a/ contains .github/workflows/{ci,tests}.yml
# as well as custom-action/action.yml
zizmor repo-a/

# or with multiple directories
zizmor repo-a/ ../../repo-b/

# collect only workflows
zizmor --collect=workflows repo-a/

Tip

Private repositories can also be audited remotely, as long as your GitHub API token has sufficient permissions.

Tip

Pass --collect=workflows to disable collecting anything except workflow definitions.

zizmor can also fetch workflows and actions directly from GitHub, if given a GitHub API token via GH_TOKEN or --gh-token:

# audit all workflows and composite actions in zizmorcore/zizmor
# assumes you have `gh` installed
zizmor --gh-token=$(gh auth token) zizmorcore/zizmor

Multiple repositories will also work:

zizmor --gh-token=$(gh auth token) zizmorcore/zizmor zizmorcore/gha-hazmat

As will the @<ref> syntax for auditing a specific tag, branch, or commit:

zizmor --gh-token=$(gh auth token) actions/checkout@v7

See Usage for more examples, including examples of configuration.

Fixing findings🔗

Some findings can be fixed automatically by running zizmor with --fix.

For findings that can't be fixed automatically, consult the documentation for the relevant audit rule. In many modern terminals, the audit rule name in the terminal output is a link that goes directly to that rule's documentation. For example, in this output:

error[template-injection]: code injection via template expansion

template-injection within the square brackets is a clickable link that takes you to the template-injection audit documentation. See Audit documentation links for more detail.

For findings that aren't right for your use case that you want to ignore, you can add a # zizmor: ignore[rulename] comment to the relevant line. More details, including how to ignore multiple findings or entire files by using a zizmor.yml configuration file, are in the Ignoring results section.