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] <INPUTS>...

Arguments:
  <INPUTS>...  The inputs to audit

Options:
  -p, --pedantic
          Emit 'pedantic' findings
      --persona <PERSONA>
          The persona to use while auditing [default: regular] [possible values: auditor, pedantic, regular]
  -o, --offline
          Perform only offline operations [env: ZIZMOR_OFFLINE=]
      --gh-token <GH_TOKEN>
          The GitHub API token to use [env: GH_TOKEN=]
      --no-online-audits
          Perform only offline audits [env: ZIZMOR_NO_ONLINE_AUDITS=]
  -v, --verbose...
          Increase logging verbosity
  -q, --quiet...
          Decrease logging verbosity
      --format <FORMAT>
          The output format to emit. By default, plain text will be emitted [default: plain] [possible values: plain, json, sarif]
  -c, --config <CONFIG>
          The configuration file to load. By default, any config will be discovered relative to $CWD
      --no-config
          Disable all configuration loading
      --no-exit-codes
          Disable all error codes besides success and tool failure
      --min-severity <MIN_SEVERITY>
          Filter all results below this severity [possible values: unknown, informational, low, medium, high]
      --min-confidence <MIN_CONFIDENCE>
          Filter all results below this confidence [possible values: unknown, low, medium, high]
      --cache-dir <CACHE_DIR>
          The directory to use for HTTP caching. By default, a host-appropriate user-caching directory will be used
  -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 workflows as explicit inputs:

zizmor ci.yml tests.yml lint.yml

These can be in any directory as well:

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

If you have multiple workflows in a single directory, zizmor will discover them:

# somewhere/ contains ci.yml and tests.yml
zizmor somewhere/

Moreover, if the specified directory contains a .github/workflows subdirectory, zizmor will discover workflows there:

# my-local-repo/ contains .github/workflows/{ci,tests}.yml
zizmor my-local-repo/

Tip

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

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

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

Multiple repositories will also work:

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

See Usage for more examples, including examples of configuration.