basecamp/house-skills/harden-github-actions

Resolving Zizmor Warnings in GitHub Actions

Overview

zizmor identifies security vulnerabilities in GitHub Actions workflows. This skill documents the decision guidelines for resolving each warning type: when to fix, how to fix, and when to suppress with an inline comment explaining why.

Core principle: Fix the vulnerability whenever possible. Suppress only when the fix would break required functionality, and always include a reason in the suppression comment.

Prerequisites

This work should be done on a branch in a git worktree. Before starting any work, verify you are in the worktree directory and on the correct branch:

pwd          # should be the worktree path
git branch   # should show the feature branch, not main

Workflow Order

This ordering governs a zizmor-hardening pass. If you are here only to schedule a vulnerability scanner or to sort out a pinned toolchain, go straight to "Advisory scanning: put it on a clock, not on the diff" — those tasks stand on their own and do not require a repository-wide hardening pass first.

Always work in this order. Each step is a separate commit.

1. Add zizmor CI job using the standard template
2. Configure dependabot to batch github-actions updates weekly
3. Add local workflow linting to bin/setup and bin/ci (see below). Skip if these

scripts don't exist in the project.

1. Pin actions with pinact run
2. Address zizmor warnings by severity (high → medium → low → informational).
3. Ensure all permissions are job-level. Check every workflow file for top-level

permissions: blocks. Replace with permissions: {} and add per-job permissions. This goes beyond what zizmor flags — zizmor misses single-job workflows. Commit.

1. Run actionlint and fix any findings. Commit.

Running pinact

Run pinact run --min-age 7 from the repository root. This pins all actions in .github/workflows/ to SHA hashes, skipping any versions published less than 7 days ago.

This value must match `default-days` in `dependabot.yml` — otherwise dependabot will propose updates that pinact refuses to pin, or pinact will pin versions dependabot has not yet cleared.

Do not re-run `pinact run` after adding inline suppressions. pinact requires the # vX.Y.Z version comment to sit immediately after the SHA. When a zizmor: ignore comment sits between the SHA and the version comment (the placement dependabot requires, see Suppression Format), a re-run rewrites the line and silently deletes the suppression. This is safe in practice because pinact runs only during this one-time hardening pass: it is not added to CI, bin/ci, or bin/setup, and dependabot handles later version bumps by updating the SHA and the trailing # vX.Y.Z while preserving the comment in between. So pin first (this step), then add suppressions while addressing findings, and do not pin again. If you must re-pin later, re-add the suppressions afterward and verify with zizmor.

Running zizmor

Always run zizmor with a GitHub token so that online audits (like ref-version-mismatch and impostor-commit) can resolve SHAs against the GitHub API. Without a token, these audits are silently skipped and findings will only surface in CI.

GITHUB_TOKEN=$(gh auth token) zizmor .

Filter severity by passing the flag --min-severity=<level> where level can be high, medium, or low. Informational warnings may be emitted by omitting this flag entirely.

Auto-fix workflow

For each severity level (high, then medium, then low, then informational):

1. Run zizmor --fix=all --min-severity=<level> . to auto-correct fixable findings (--fix alone uses safe mode which silently holds back some fixes; use --fix=all and rely on diff review as the safety net)
2. STOP and review the diff. Check each auto-fix against the Decision Guide below.

• cache-poisoning fixes will disable caching — almost always revert these and suppress instead
• artipacked fixes add persist-credentials: false — revert if the workflow needs git push
• superfluous-actions fixes replace actions with inline code — always revert these and suppress instead
• bot-conditions auto-fix replaces github.actor with user.login — revert and apply the dual check instead (see rule file)
• template-injection fixes are generally correct

1. Revert any incorrect fixes
2. For reverted fixes, apply the correct resolution manually (e.g., suppress with a reason)
3. Manually fix anything --fix didn't handle. For `excessive-permissions`: you MUST research each action's permissions. Do not guess. See the permission research process below.
4. Run zizmor --min-severity=<level> . to verify a clean check at this severity level
5. Commit

After completing all default severity levels, run a pedantic pass:

1. Run zizmor --persona=pedantic --min-severity=high .
2. Address findings the same way as above — the most common pedantic finding is

excessive-permissions on single-job workflows where zizmor's default persona doesn't flag it. Apply the same fix: permissions: {} at workflow level, scoped per job.

1. Run zizmor --persona=pedantic --min-severity=high . to verify clean
2. Commit

Decision Guide by Rule

When you encounter a zizmor finding, read the corresponding rule file in references/ for full decision guidance, suppression checklists, and examples. Only read the rules you need.

Permission mappings for excessive-permissions are in references/permission-mappings.md.

For findings not covered in this skill, consult https://docs.zizmor.sh/audits/ for detailed explanations and resolution guidance.

Suppression Format

Always use inline comments with the rule name and a reason:

# zizmor: ignore[rule-name] -- reason why suppression is necessary

The -- separator before the reason is a convention for readability. Never suppress without a reason. If you can't articulate why the fix would break something, apply the fix instead.

Suppressing on a pinned action

When the suppression lands on a uses: line that pinact has pinned, the zizmor: ignore comment goes between the SHA and the version-pin comment, leaving # vX.Y.Z last:

uses: ruby/setup-ruby@<sha> # zizmor: ignore[cache-poisoning] -- reason # v1.302.0

Dependabot reads the trailing # vX.Y.Z comment to track the pinned version, so it must be the last comment on the line. Do not put the version comment first (# v1.302.0 # zizmor: ...): pinact tolerates that order, but dependabot will no longer recognize the pin and will stop proposing updates for that action. This ordering interacts with re-running pinact, so read the warning under "Running pinact".

Standard Zizmor CI Job

Add this job to the repository's main CI workflow file (often ci.yml or ci-checks.yml).

Placement matters. Before inserting, find the existing lint job (rubocop, eslint, golangci-lint, etc.) in the workflow and place lint-actions immediately after it. If there is no lint job, place it immediately before the first test job. Never append it to the end of the file — it is a linting concern, not a test or deployment step:

lint-actions:
  name: GitHub Actions audit
  runs-on: ubuntu-latest
 
  steps:
    - uses: actions/checkout@v6
      with:
        persist-credentials: false
 
    - name: Run actionlint
      uses: rhysd/actionlint@v1.7.11
 
    - name: Run zizmor
      uses: zizmorcore/zizmor-action@v0.6.2
      with:
        advanced-security: false

Use version tags, not SHA hashes — run pinact run --min-age 7 immediately after adding this job to pin them. This ensures the SHAs match what pinact produces for the rest of the workflow.

Before adding this job, check if the workflow already has a standalone `actionlint` job. If it does, remove it — lint-actions replaces it. Do not create duplicate actionlint runs.

Local Workflow Linting

If the project has a bin/ci script (or equivalent like config/ci.rb), add workflow linting so developers catch issues locally before pushing. If bin/setup also exists, add tool installation there too. Skip this section entirely if there is no local CI script.

bin/setup — tool installation

Check if actionlint, shellcheck, and zizmor are already installed. If not, install them using the platform's package manager. Read the existing bin/setup script to understand its conventions before adding to it.

shellcheck is required — actionlint uses it to lint shell scripts in run: blocks. Without shellcheck, actionlint silently skips script checks and local results won't match CI.

Install all three tools using the same pattern:

for tool in actionlint shellcheck zizmor; do
  if ! command -v "$tool" &> /dev/null; then
    if command -v brew &> /dev/null; then
      brew install "$tool"
    elif command -v pacman &> /dev/null; then
      sudo pacman -S --noconfirm "$tool"
    else
      echo "Error: install $tool manually" >&2
      exit 1
    fi
  fi
done

Adapt this to match the script's existing style (e.g., if it uses functions, conditionals, or a different error pattern, follow that convention).

bin/ci — running the linters

Add actionlint and zizmor as separate steps. Read the existing bin/ci script to understand its conventions before adding to it.

# Lint GitHub Actions workflows
actionlint
zizmor .

Each tool should be a separate command so failures are clearly attributable. Place these near other linting steps if the script has them.

Examples

• bin/setup + config/ci.rb: lexxy#882
• Makefile: basecamp-sdk@aa1f2d50

Dependabot Configuration

GitHub Actions entry

Ensure .github/dependabot.yml includes a github-actions entry with batching. The schedule must be weekly — not daily.

- package-ecosystem: github-actions
  directory: "/"
  groups:
    github-actions:
      patterns:
        - "*"
  schedule:
    interval: weekly
  cooldown:
    default-days: 7

The groups block batches all action updates into a single PR instead of one PR per action.

Cooldown on all ecosystems

Add cooldown to every ecosystem entry in dependabot.yml. Use semver-granular cooldowns for real package ecosystems so low-risk patches flow faster while major bumps get more soak time: