docs: add troubleshooting page (#1296)

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

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

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

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
 

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)!

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.

mkdocs.yml

@@ -14,6 +14,7 @@ nav:
   - "quickstart.md"
   - "usage.md"
   - "integrations.md"
+  - "troubleshooting.md"
   - "release-notes.md"
   - "configuration.md"
   - "audits.md"