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=]
      --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=]
  -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
      --collect <COLLECT>
          Control which kinds of inputs are collected for auditing [default: all] [possible values: all, workflows-only, actions-only]
  -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 or composite actions as explicit inputs:

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

Composite action support was added in v1.0.0.

Tip

Pass --collect=workflows-only to disable collecting composite actions.

When given one or more local directories, zizmor will treat each as a GitHub repository and attempt to discover workflows defined under the .github/workflows subdirectory for each. zizmor will also walk each directory to find composite action definitions (action.yml in any subdirectory).

# 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, not composite actions
zizmor --collect=workflows-only

Tip

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

Tip

Pass --collect=workflows-only to disable collecting composite actions.

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