From 73dfa03a417416a64da130072788efc8cb265b8c Mon Sep 17 00:00:00 2001
From: William Woodruff <william@yossarian.net>
Date: Thu, 5 Jun 2025 00:05:21 -0400
Subject: [PATCH] docs: mention zizmorcore/zizmor-action (#895)

---
 docs/assets/chips.css | 29 ++++++++++++++++++++
 docs/usage.md         | 61 ++++++++++++++++++++++++++++++++++++++++---
 mkdocs.yml            |  1 +
 3 files changed, 87 insertions(+), 4 deletions(-)
 create mode 100644 docs/assets/chips.css

diff --git a/docs/assets/chips.css b/docs/assets/chips.css
new file mode 100644
index 00000000..b745b527
--- /dev/null
+++ b/docs/assets/chips.css
@@ -0,0 +1,29 @@
+.chip-recommended {
+    display: inline-block;
+    background: green;
+    color: white;
+    padding: 0px 6px;
+    border-radius: 10px;
+    font-size: x-small;
+    vertical-align: middle;
+}
+
+.chip-recommended::before {
+    content: "recommended";
+    font-style: normal;
+}
+
+.chip-expert {
+    display: inline-block;
+    background: blue;
+    color: white;
+    padding: 0px 6px;
+    border-radius: 10px;
+    font-size: x-small;
+    vertical-align: middle;
+}
+
+.chip-expert::before {
+    content: "for experts";
+    font-style: normal;
+}
diff --git a/docs/usage.md b/docs/usage.md
index 8cbaf447..44f53643 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -618,13 +618,66 @@ zizmor --cache-dir /tmp/zizmor ...
 
 ### Use in GitHub Actions
 
-`zizmor` is designed to integrate with GitHub Actions. There are
-two primary ways to use `zizmor` in GitHub Actions:
+`zizmor` is designed to integrate with GitHub Actions.
 
-1. With `--format=sarif` via Advanced Security (recommended)
+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](#manual-integration) steps further below.
+
+#### With @zizmorcore/zizmor-action *&nbsp;*{.chip-recommended}
+
+To get started with @zizmorcore/zizmor-action, you can use the following
+workflow skeleton:
+
+```yaml title="zizmor.yml"
+name: GitHub Actions Security Analysis with zizmor 🌈
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["**"]
+
+permissions: {}
+
+jobs:
+  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][inputs-documentation] for
+additional configuration options.
+
+[inputs-documentation]: https://github.com/zizmorcore/zizmor-action#inputs
+
+#### Manual integration *&nbsp;*{.chip-expert}
+
+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 *&nbsp;*{.chip-recommended}
 2. With `--format=github` via GitHub Annotations
 
-=== "With Advanced Security (recommended)"
+=== "With Advanced Security *&nbsp;*{.chip-recommended}"
 
     GitHub's Advanced Security and [code scanning functionality] supports
     [SARIF], which `zizmor` can produce via `--format=sarif`.
diff --git a/mkdocs.yml b/mkdocs.yml
index d52e307d..1697c50d 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -107,6 +107,7 @@ validation:
 
 extra_css:
   - assets/magiclink.css
+  - assets/chips.css
 
 exclude_docs: |
   snippets/