Harden GitHub Actions with zizmor
zizmor is a static analyzer for GitHub Actions workflows. New workflow files —
especially ones pasted from templates or generated by an app — almost always ship
with insecure defaults (unpinned actions, no permissions boundary, credential
persistence). If the repo runs zizmor in CI, those defaults fail the pipeline; even
if it doesn't, they're real supply-chain and token-leak risks. So treat the audit as
part of writing the workflow, not a separate review step that happens later.
When this applies
Run the audit whenever you have:
- Added a new file under
.github/workflows/.
- Pasted or generated a workflow from a template (Claude GitHub App, an action's
README, a scaffolding tool).
- Edited an existing workflow's
uses:, permissions:, on:, or concurrency:.
You don't need the user to ask for "security" or mention "zizmor" — hardening is the
default expectation for any workflow you touch.
The loop
Match the repo's existing conventions first. Before inventing hardening, read a
workflow in the same repo that already passes (often ci.yml or codeql.yml). Copy
its action pins, its permission-comment style, its concurrency group naming. A
consistent repo is easier to review than a "correct" but idiosyncratic file. Use
grep -nE "uses:|permissions:|persist-credentials|concurrency:" .github/workflows/*.yml
to see what's already established.
Run the audit on the file(s) you created or changed:
uvx zizmor --persona pedantic .github/workflows/<file>.yml
--persona pedantic is the strictest mode and is what hardened repos tend to enforce
in CI, so matching it locally avoids a surprise pipeline failure. Pass every file you
touched. Exit code 0 with "No findings to report" means done.
Fix every finding, not just the error-level ones. The pedantic persona reports
informational findings too, and a CI gate with no min-severity set fails on any
finding. The common ones and their fixes are below.
Re-run until clean (exit 0). Then you're done.
Common findings → fixes
These are the recurring ones. Apply the fix that matches how the rest of the repo does it.
| Finding |
Why it matters |
Fix |
| unpinned action reference (error) |
A mutable tag like @v4 can be repointed at malicious code; pinning to a commit SHA is immutable. |
Pin to the full commit SHA with the tag in a trailing comment: uses: actions/checkout@34e1148… # v4. Resolve the SHA for an action (see below). |
| overly broad permissions |
Default GITHUB_TOKEN permissions are write-all; an exploited step can push code or open releases. |
Add top-level permissions: {} and grant each job only what it needs. |
| permissions without explanatory comments |
Reviewers can't tell why a scope was granted. |
Add an inline comment per permission line: contents: read # checkout. |
| credential persistence |
actions/checkout leaves the git token on disk by default, readable by later steps. |
Add persist-credentials: false # don't leave the git token on disk to the checkout with: block. |
| insufficient job-level concurrency limits |
Stacked runs on the same ref waste minutes and can race. |
Add a top-level concurrency: block with a group: keyed on the ref/PR and cancel-in-progress: true. |
| anonymous-definition (informational) |
An unnamed job shows up with an opaque check name. |
Give each job a name:. |
Resolving a commit SHA for an action
Lightweight tags resolve directly; annotated tags (common for @v1-style major tags)
need one extra dereference step. Use the GitHub API:
# Step 1: resolve the tag ref
gh api repos/<owner>/<repo>/git/refs/tags/<tag>
# If "object.type" is "commit", that SHA is your pin.
# If it's "tag" (annotated), dereference it:
gh api repos/<owner>/<repo>/git/tags/<tag-object-sha>
# The resulting "object.sha" (type "commit") is your pin.
Pin to that commit SHA and keep the human-readable tag in a # v1 comment so the file
stays reviewable.
Notes
uvx runs zizmor in an ephemeral environment, so nothing needs to be installed
globally. If uvx isn't available, fall back to pipx run zizmor, docker run --rm -v "$PWD":/work -w /work ghcr.io/zizmorcore/zizmor:latest, or a local zizmor.- Some findings have legitimate exceptions. If a finding genuinely doesn't apply, prefer
a scoped
# zizmor: ignore[<rule>] comment on the offending line (with a reason) over
silencing the whole audit — that keeps the rest of the file covered and documents the
decision.
- Online audits (e.g. checking whether a pinned SHA is stale) need network access and a
token; the local run above covers the static rules, which are what gate CI.
1---2name: harden-github-actions3description: Whenever you create or substantially edit a GitHub Actions workflow (.github/workflows/*.yml), run `uvx zizmor --persona pedantic` on it and fix every finding before considering the file done. Use this any time you add a new workflow, paste a template workflow (e.g. the Claude GitHub App, a marketplace action, a generated CI/CD file), or change `uses:`, `permissions:`, or trigger blocks — even if the user didn't mention security or zizmor. A workflow that hasn't been run through the pedantic audit is not finished.4---56# Harden GitHub Actions with zizmor78`zizmor` is a static analyzer for GitHub Actions workflows. New workflow files —9especially ones pasted from templates or generated by an app — almost always ship10with insecure defaults (unpinned actions, no permissions boundary, credential11persistence). If the repo runs zizmor in CI, those defaults fail the pipeline; even12if it doesn't, they're real supply-chain and token-leak risks. So treat the audit as13part of *writing* the workflow, not a separate review step that happens later.1415## When this applies1617Run the audit whenever you have:1819- Added a new file under `.github/workflows/`.20- Pasted or generated a workflow from a template (Claude GitHub App, an action's21 README, a scaffolding tool).22- Edited an existing workflow's `uses:`, `permissions:`, `on:`, or `concurrency:`.2324You don't need the user to ask for "security" or mention "zizmor" — hardening is the25default expectation for any workflow you touch.2627## The loop28291. **Match the repo's existing conventions first.** Before inventing hardening, read a30 workflow in the same repo that already passes (often `ci.yml` or `codeql.yml`). Copy31 its action pins, its permission-comment style, its concurrency group naming. A32 consistent repo is easier to review than a "correct" but idiosyncratic file. Use33 `grep -nE "uses:|permissions:|persist-credentials|concurrency:" .github/workflows/*.yml`34 to see what's already established.35362. **Run the audit** on the file(s) you created or changed:3738 ```bash39 uvx zizmor --persona pedantic .github/workflows/<file>.yml40 ```4142 `--persona pedantic` is the strictest mode and is what hardened repos tend to enforce43 in CI, so matching it locally avoids a surprise pipeline failure. Pass every file you44 touched. Exit code `0` with "No findings to report" means done.45463. **Fix every finding**, not just the error-level ones. The pedantic persona reports47 informational findings too, and a CI gate with no `min-severity` set fails on any48 finding. The common ones and their fixes are below.49504. **Re-run until clean** (exit 0). Then you're done.5152## Common findings → fixes5354These are the recurring ones. Apply the fix that matches how the rest of the repo does it.5556| Finding | Why it matters | Fix |57|---|---|---|58| **unpinned action reference** (error) | A mutable tag like `@v4` can be repointed at malicious code; pinning to a commit SHA is immutable. | Pin to the full commit SHA with the tag in a trailing comment: `uses: actions/checkout@34e1148… # v4`. Resolve the SHA for an action (see below). |59| **overly broad permissions** | Default `GITHUB_TOKEN` permissions are write-all; an exploited step can push code or open releases. | Add top-level `permissions: {}` and grant each job only what it needs. |60| **permissions without explanatory comments** | Reviewers can't tell why a scope was granted. | Add an inline comment per permission line: `contents: read # checkout`. |61| **credential persistence** | `actions/checkout` leaves the git token on disk by default, readable by later steps. | Add `persist-credentials: false # don't leave the git token on disk` to the checkout `with:` block. |62| **insufficient job-level concurrency limits** | Stacked runs on the same ref waste minutes and can race. | Add a top-level `concurrency:` block with a `group:` keyed on the ref/PR and `cancel-in-progress: true`. |63| **anonymous-definition** (informational) | An unnamed job shows up with an opaque check name. | Give each job a `name:`. |6465### Resolving a commit SHA for an action6667Lightweight tags resolve directly; annotated tags (common for `@v1`-style major tags)68need one extra dereference step. Use the GitHub API:6970```bash71# Step 1: resolve the tag ref72gh api repos/<owner>/<repo>/git/refs/tags/<tag>73# If "object.type" is "commit", that SHA is your pin.74# If it's "tag" (annotated), dereference it:75gh api repos/<owner>/<repo>/git/tags/<tag-object-sha>76# The resulting "object.sha" (type "commit") is your pin.77```7879Pin to that commit SHA and keep the human-readable tag in a `# v1` comment so the file80stays reviewable.8182## Notes8384- `uvx` runs zizmor in an ephemeral environment, so nothing needs to be installed85 globally. If `uvx` isn't available, fall back to `pipx run zizmor`, `docker run --rm86 -v "$PWD":/work -w /work ghcr.io/zizmorcore/zizmor:latest`, or a local `zizmor`.87- Some findings have legitimate exceptions. If a finding genuinely doesn't apply, prefer88 a scoped `# zizmor: ignore[<rule>]` comment on the offending line (with a reason) over89 silencing the whole audit — that keeps the rest of the file covered and documents the90 decision.91- Online audits (e.g. checking whether a pinned SHA is stale) need network access and a92 token; the local run above covers the static rules, which are what gate CI.
alexanderop