diff --git a/.github/ISSUE_TEMPLATE/bug-report.yml b/.github/ISSUE_TEMPLATE/bug-report.yml index 0e688402..32a5f81e 100644 --- a/.github/ISSUE_TEMPLATE/bug-report.yml +++ b/.github/ISSUE_TEMPLATE/bug-report.yml @@ -26,6 +26,10 @@ body: I am **not** filing a feature request. These should be filed via the feature request form instead. required: true + - label: >- + I have checked the [Troubleshooting Guide](https://docs.zizmor.sh/troubleshooting) + for my problem. + required: true - label: >- I have looked through both the [open](https://github.com/zizmorcore/zizmor/issues?q=is%3Aissue+is%3Aopen+) diff --git a/.github/pinact.yml b/.github/pinact.yml index 1a922e80..ac26150e 100644 --- a/.github/pinact.yml +++ b/.github/pinact.yml @@ -4,3 +4,8 @@ files: # NOTE: we intentionally only update docs with pinact. # All non-doc workflows and actions are updated through Dependabot. - pattern: ../docs/integrations.md + - pattern: ../docs/troubleshooting.md + +ignore_actions: + - name: example/.* # used for examples + ref: .* diff --git a/docs/index.md b/docs/index.md index 55fb2bdf..491af7b3 100644 --- a/docs/index.md +++ b/docs/index.md @@ -36,7 +36,7 @@ many common security issues in typical GitHub Actions CI/CD setups. [:octicons-arrow-right-24: Usage recipes](./usage.md) -- :material-robot-love:{.lg .middle} Integration +- :material-robot-love:{.lg .middle} Integrations --- diff --git a/docs/installation.md b/docs/installation.md index 4d73dddc..fb1b01ad 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -8,7 +8,7 @@ description: Installation instructions for zizmor. `zizmor` is available within several packaging ecosystems. -=== ":simple-homebrew: Homebrew" +=== ":simple-homebrew: Homebrew" { #homebrew } ![Homebrew Formula Version](https://img.shields.io/homebrew/v/zizmor) @@ -18,7 +18,7 @@ description: Installation instructions for zizmor. brew install zizmor ``` -=== ":simple-pypi: PyPI" +=== ":simple-pypi: PyPI" { #pypi } ![PyPI - Version](https://img.shields.io/pypi/v/zizmor) @@ -45,7 +45,7 @@ description: Installation instructions for zizmor. uvx zizmor --help ``` -=== ":simple-rust: crates.io" +=== ":simple-rust: crates.io" { #cratesio } ![Crates.io Version](https://img.shields.io/crates/v/zizmor) @@ -61,7 +61,7 @@ description: Installation instructions for zizmor. cargo install --locked zizmor ``` -=== ":simple-docker: Docker" +=== ":simple-docker: Docker" { #docker } An official `zizmor` image is available from the [GitHub Container Registry](https://ghcr.io/zizmorcore/zizmor): @@ -69,7 +69,7 @@ description: Installation instructions for zizmor. docker pull ghcr.io/zizmorcore/zizmor:latest ``` -=== ":simple-anaconda: Conda" +=== ":simple-anaconda: Conda" { #conda } [![Anaconda-Server Badge](https://anaconda.org/conda-forge/zizmor/badges/version.svg)](https://anaconda.org/conda-forge/zizmor) [![Anaconda-Server Badge](https://anaconda.org/conda-forge/zizmor/badges/latest_release_date.svg)](https://anaconda.org/conda-forge/zizmor) @@ -89,7 +89,7 @@ description: Installation instructions for zizmor. for additional information. -=== ":material-nix: Nix" +=== ":material-nix: Nix" { #nix } [![nixpkgs unstable package](https://repology.org/badge/version-for-repo/nix_unstable/zizmor.svg)](https://repology.org/project/zizmor/versions) @@ -105,7 +105,7 @@ description: Installation instructions for zizmor. nix profile install nixpkgs#zizmor ``` -=== ":simple-archlinux: Arch Linux" +=== ":simple-archlinux: Arch Linux" { #archlinux } [![Arch Linux package](https://repology.org/badge/version-for-repo/arch/zizmor.svg)](https://repology.org/project/zizmor/versions) @@ -118,7 +118,7 @@ description: Installation instructions for zizmor. pacman -S zizmor ``` -=== "Chimera Linux" +=== "Chimera Linux" { #chimeralinux } [![Chimera Linux package](https://repology.org/badge/version-for-repo/chimera/zizmor.svg)](https://repology.org/project/zizmor/versions) @@ -135,7 +135,7 @@ description: Installation instructions for zizmor. apk add zizmor ``` -=== ":simple-alpinelinux: Alpine Linux" +=== ":simple-alpinelinux: Alpine Linux" { #alpinelinux } [![Alpine Linux package](https://repology.org/badge/version-for-repo/alpine_edge/zizmor.svg)](https://repology.org/project/zizmor/versions) @@ -147,7 +147,7 @@ description: Installation instructions for zizmor. apk add zizmor ``` -=== "Other ecosystems" +=== "Other ecosystems" { #other-ecosystems } !!! info diff --git a/docs/integrations.md b/docs/integrations.md index cbbfa15b..a3d78180 100644 --- a/docs/integrations.md +++ b/docs/integrations.md @@ -99,7 +99,7 @@ GitHub Actions setup: persist-credentials: false - name: Install the latest version of uv - uses: astral-sh/setup-uv@b75a909f75acd358c2196fb9a5f1299a9a8868a4 # v6.7.0 + uses: astral-sh/setup-uv@85856786d1ce8acfbcc2f13a5f3fbd6b938f9f41 # v7.1.2 - name: Run zizmor 🌈 run: uvx zizmor --format=sarif . > results.sarif # (2)! @@ -107,7 +107,7 @@ GitHub Actions setup: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} # (1)! - name: Upload SARIF file - uses: github/codeql-action/upload-sarif@192325c86100d080feab897ff886c34abd4c83a3 # v3.30.3 + uses: github/codeql-action/upload-sarif@4e94bd11f71e507f7f87df81788dff88d1dacbfb # v4.31.0 with: sarif_file: results.sarif category: zizmor @@ -168,7 +168,7 @@ GitHub Actions setup: uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 - name: Install the latest version of uv - uses: astral-sh/setup-uv@b75a909f75acd358c2196fb9a5f1299a9a8868a4 # v6.7.0 + uses: astral-sh/setup-uv@85856786d1ce8acfbcc2f13a5f3fbd6b938f9f41 # v7.1.2 - name: Run zizmor 🌈 run: uvx zizmor --format=github . # (2)! diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 00000000..b4218f55 --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,115 @@ +This page documents some of the common issues that people run into when +installing or using `zizmor`. + +!!! tip + + Don't see your issue here? Let us know by opening an issue, + and consider contributing it! + +## Installation issues + +### `cargo install zizmor` fails + +If you install `zizmor` from crates.io using `cargo install zizmor`, you +may occasionally run into build errors that look like this: + +``` +error: failed to compile `zizmor vA.B.C`, intermediate artifacts can be found at `/SOME/TEMP/DIR`. +To reuse those artifacts with a future compilation, set the environment variable `CARGO_TARGET_DIR` to that path. + +Caused by: + failed to select a version for the requirement `SOMEDEP = "^X.Y.Z"` + version X.Y.Z is yanked + location searched: crates.io index + required by package `zizmor vA.B.C` +``` + +This happens when one or more of `zizmor`'s dependencies has a yanked version +that the requested version of `zizmor` depends on. + +If you run into this issue, you have two options: + +1. Install `zizmor` from one of the binary distributions sources + recommended in the [installation docs](./installation.md). + **This is the recommended option.** +2. Use the `--locked` flag with `cargo install`: + + ```bash + cargo install --locked zizmor + ``` + + This will force `cargo` to use the exact dependencies specified in + `zizmor`'s `Cargo.lock` file, overriding any yanked versions. + +## Runtime errors + +### "can't access ORG/REPO: missing or you have no access" + +When running `zizmor` in an online mode, you might see an error like this: + +``` +fatal: no audit was performed +ref-confusion failed on https://github.com/example/repoA/.github/workflows/ci.yml + +Caused by: + 0: couldn't list branches for example/repoB + 1: can't access example/repoB: missing or you have no access +``` + +This error means that `zizmor` was able to retrieve your inputs, +but that those inputs include a _reference_ (such as a `#!yaml uses:` clause) +that `zizmor` cannot access. + +A common scenario that causes this is as follows: + +1. You enable `zizmor` in GitHub Actions on `example/repoA` (public _or_ + private), via @zizmorcore/zizmor-action. This action uses the default + `secrets.GITHUB_TOKEN` to perform online audits. +2. `example/repoA` has a workflow that uses an action or reusable workflow +from a different private repository, e.g. `example/repoB`. + + For example: + + ```yaml title="example/repoA/.github/workflows/ci.yml" + - uses: example/repoB/some-internal-action@v1.0.0 + ``` + +3. `zizmor` tries to access `example/repoB` to analyze the referenced + action, but the `GITHUB_TOKEN` provided to the action only has access + to `example/repoA`, not `example/repoB`. + +This happens because the default `GITHUB_TOKEN` provided to GitHub Actions +does not have private repository access across different repositories, +by design. See orgs/community?46566 for additional information on this +behavior. + +If you run into this issue, you have two options: + +1. You can run `zizmor` in offline mode, e.g. with `--offline` or + `#!yaml online-audits: false` in the action's settings. This will prevent + all online accesses that could fail across repository boundaries, + at the cost of disabling online audits. + +2. You can provide a custom PAT to `zizmor` that provides read access to the + necessary repositories. You can do this by creating a new fine-grained PAT + with only the "Contents: read-only" permission for the relevant repositories. + + This PAT can then be provided to `zizmor` via `--gh-token` or `GITHUB_TOKEN` + on the command line, or via the `token` input to the GitHub Action + (once you've added your PAT to your repository secrets). + + For example, if you've configured the PAT as `ZIZMOR_GH_TOKEN` + in your repository secrets, you could do: + + ```yaml title="example/repoA/.github/workflows/ci.yml" hl_lines="3" + - uses: zizmorcore/zizmor-action@e673c3917a1aef3c65c972347ed84ccd013ecda4 # v0.2.0 + with: + token: ${{ secrets.ZIZMOR_GH_TOKEN }} + ``` + + !!! important + + The **only** permission that `zizmor` itself needs is "Contents: read-only". + + You should always reduce the risk of token leakage by granting + **only the minimum** necessary permissions. diff --git a/mkdocs.yml b/mkdocs.yml index 8f6bfa96..08eb1771 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -14,6 +14,7 @@ nav: - "quickstart.md" - "usage.md" - "integrations.md" + - "troubleshooting.md" - "release-notes.md" - "configuration.md" - "audits.md"