Skip to content

Integrations

GitHub Actions🔗

zizmor is designed to integrate with GitHub Actions.

The easiest way to use zizmor in GitHub Actions is with zizmorcore/zizmor-action. However, expert users or those who want more fine-grained control over their integration can also use the Manual integration steps further below.

Via zizmorcore/zizmor-action ​🔗

To get started with zizmorcore/zizmor-action, you can use the following workflow skeleton:

zizmor.yml
name: GitHub Actions Security Analysis with zizmor 🌈

on:
  push:
    branches: ["main"]
  pull_request:
    branches: ["**"]

permissions: {}

jobs:
  zizmor:
    name: Run zizmor 🌈
    runs-on: ubuntu-latest
    permissions:
      security-events: write
      contents: read # only needed for private repos
      actions: read # only needed for private repos
    steps:
      - name: Checkout repository
        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
        with:
          persist-credentials: false

      - name: Run zizmor 🌈
        uses: zizmorcore/zizmor-action@f52a838cfabf134edcbaa7c8b3677dde20045018 # v0.1.1

See the action's inputs documentation for additional configuration options.

Manual integration ​🔗

If you don't want to use zizmorcore/zizmor-action, you can always use zizmor directly in your GitHub Actions workflows.

All of the same functionality is available, but you'll need to do a bit more explicit scaffolding.

There are two main ways to manually integrate zizmor into your GitHub Actions setup:

  1. With --format=sarif via Advanced Security ​
  2. With --format=github via GitHub Annotations

GitHub's Advanced Security and code scanning functionality supports SARIF, which zizmor can produce via --format=sarif.

Important

The workflow below performs a SARIF upload, which is available for public repositories and for GitHub Enterprise Cloud organizations that have Advanced Security. If neither of these apply to you, then you can use --format=github or adapt the --format=json or --format=plain output formats to your needs.

zizmor.yml
name: GitHub Actions Security Analysis with zizmor 🌈

on:
  push:
    branches: ["main"]
  pull_request:
    branches: ["**"]

permissions: {}

jobs:
  zizmor:
    name: zizmor latest via PyPI
    runs-on: ubuntu-latest
    permissions:
      security-events: write # needed for SARIF uploads
      contents: read # only needed for private repos
      actions: read # only needed for private repos
    steps:
      - name: Checkout repository
        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
        with:
          persist-credentials: false

      - name: Install the latest version of uv
        uses: astral-sh/setup-uv@6b9c6063abd6010835644d4c2e1bef4cf5cd0fca # v6.0.1

      - name: Run zizmor 🌈
        run: uvx zizmor --format=sarif . > results.sarif # (2)!
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} # (1)!

      - name: Upload SARIF file
        uses: github/codeql-action/upload-sarif@ff0a06e83cb2de871e5a09832bc6a81e7276941f # v3.28.18
        with:
          sarif_file: results.sarif
          category: zizmor

  1. Optional: Remove the env: block to only run zizmor's offline audits.

  2. This installs the zizmor package from PyPI, since it's pre-compiled and therefore completes much faster. You could instead compile zizmor within CI/CD with cargo install zizmor.

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

A simpler (but more limited) way to use zizmor in GitHub Actions is with annotations, which zizmor can produce via --format=github.

This is a good option if:

  1. You don't have Advanced Security (or you don't want to use it)
  2. You don't want to run zizmor with security-events: write
zizmor.yml
name: GitHub Actions Security Analysis with zizmor 🌈

on:Use with
  push:
    branches: ["main"]
  pull_request:
    branches: ["**"]

jobs:
  zizmor:
    name: zizmor latest via PyPI
    runs-on: ubuntu-latest
    permissions:
      contents: read # only needed for private repos
      actions: read # only needed for private repos
    steps:
      - name: Checkout repository
        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2

      - name: Install the latest version of uv
        uses: astral-sh/setup-uv@6b9c6063abd6010835644d4c2e1bef4cf5cd0fca # v6.0.1

      - name: Run zizmor 🌈
        run: uvx zizmor --format=github . # (2)!
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} # (1)!

  1. Optional: Remove the env: block to only run zizmor's offline audits.

  2. This installs the zizmor package from PyPI, since it's pre-compiled and therefore completes much faster. You could instead compile zizmor within CI/CD with cargo install zizmor.

Warning

GitHub Actions has a limit of 10 annotations per step.

If your zizmor run produces more than 10 findings, only the first 10 will be rendered; all subsequent findings will be logged in the actions log but will not be rendered as annotations.

IDEs ​🔗

Warning

zizmor's LSP support is currently experimental and subject to breaking changes.

You will encounter bugs while experimenting with it; please file them!

Note

IDE integration via LSP is available in v1.11.0 and later.

zizmor can be integrated directly into your IDE or editor of choice, giving you real-time feedback on your workflows and action definitions.

Visual Studio Code🔗

zizmor has an official extension for Visual Studio Code!

You can install it from the Visual Studio Marketplace. The extension does not come with zizmor itself, so you will need to separately install zizmor in order for the extension to work.

See zizmorcore/zizmor-vscode for full installation and configuration instructions.

Generic LSP integration🔗

zizmor can be integrated with any editor or IDE that supports LSP.

To run zizmor in LSP mode, you can use the --lsp flag:

zizmor --lsp

In this mode, zizmor takes no other arguments and will communicate with the editor over stdin and stdout. No other transports are supported.

pre-commit🔗

zizmor can be used with the pre-commit framework. To do so, add the following to your .pre-commit-config.yaml repos: section:

- repo: https://github.com/zizmorcore/zizmor-pre-commit
  rev: v1.11.0 # (1)!
  hooks:
  - id: zizmor
  1. Don't forget to update this version to the latest zizmor release!

This will run zizmor on every commit.

Tip

If you want to run zizmor only on specific files, you can use the files option. This setting is optional, as zizmor will scan the entire repository by default.

See pre-commit documentation for more information on how to configure pre-commit.

Tab completion🔗

Note

Tab completion is available in v1.7.0 and later.

zizmor comes with built-in tab completion support for many popular shells. It supports all of the shells supported by clap_complete, which includes popular shells like bash, zsh, and fish.

To enable tab completion, you can use the --completions=<shell> flag to emit a completion script for the specified shell. For example, to enable tab completion for bash, you can run:

zizmor --completions=bash > ~/.bash_completion.d/zizmor # (1)!
  1. The correct location of your completion script will depend on your shell and its configuration. Consult your shell's documentation for more information.