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:
      --lsp
          Run in language server mode (EXPERIMENTAL)
  -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
      --no-progress
          Don't show progress bars, even if the terminal supports them
      --format <FORMAT>
          The output format to emit. By default, cargo-style diagnostics will be emitted [default: plain] [possible values: plain, json, json-v1, sarif, github]
      --color <MODE>
          Control the use of color in output [possible values: auto, always, never]
  -c, --config <CONFIG>
          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
      --no-exit-codes
          Disable all error codes besides success and tool failure
      --min-severity <MIN_SEVERITY>
          Filter all results below this severity [possible values: informational, low, medium, high]
      --min-confidence <MIN_CONFIDENCE>
          Filter all results below this confidence [possible values: 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: default] [possible values: all, default, workflows, actions, dependabot]
      --strict-collection
          Fail instead of warning on syntax and schema errors in collected inputs
      --completions <SHELL>
          Generate tab completion scripts for the specified shell [possible values: bash, elvish, fish, nushell, powershell, zsh]
      --fix[=<MODE>]
          Fix findings automatically, when available (EXPERIMENTAL) [possible values: safe, unsafe-only, all]
      --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 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 to avoid collecting anything except workflow definitions.

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) and Dependabot configuration files (.github/dependabot.yml).

# 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 or Dependabot configs
zizmor --collect=workflows

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

See Usage for more examples, including examples of configuration.