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

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. 4. Pin actions with pinact run 5. Address zizmor warnings by severity (high → medium → low → informational). 6. 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. 7. Run actionlint and fix any findings. Commit.

Running pinact

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

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

3. Revert any incorrect fixes 4. For reverted fixes, apply the correct resolution manually (e.g., suppress with a reason) 5. 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. 6. Run zizmor --min-severity=<level> . to verify a clean check at this severity level 7. 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. 3. Run zizmor --persona=pedantic --min-severity=high . to verify clean 4. 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.

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.5.2
      with:
        advanced-security: false

Use version tags, not SHA hashes — run pinact run --min-age 10 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:

# For package ecosystems (bundler, npm, gomod, gradle, pip, etc.)
cooldown:
  semver-major-days: 7
  semver-minor-days: 3
  semver-patch-days: 2
  default-days: 7

# For github-actions (semver-granular keys are NOT supported)
cooldown:
  default-days: 7

If an ecosystem entry is missing the cooldown block, add it. If an existing cooldown block has different values, override them with the values above — these are the standard.

Common Mistakes

Common PR Feedback (Incorrect or Misleading)

Automated reviewers (Copilot, cubic, etc.) frequently flag these. They are wrong or misleading — dismiss them.

GitHub Actions Permission Mappings

GITHUB_TOKEN permission requirements for common GitHub Actions. Used by the harden-github-actions skill when resolving excessive-permissions findings.

If an action is not in this table, you MUST fetch its README on GitHub and read the documented permission requirements before proceeding. Then add it to this table.

Actions

Common patterns (not specific actions)

artipacked — Credential Persistence After Checkout

actions/checkout persists git credentials by default, which later steps can exfiltrate.

Fix (default): Add persist-credentials: false to every actions/checkout step.

- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
  with:
    persist-credentials: false

Suppress only if ALL of these are true: 1. A later step in the SAME job runs git push, git tag, or similar write operation 2. The push target is the same repository (not a fork or external repo requiring a PAT) 3. No other authentication mechanism (e.g., deploy key, PAT) is used for the push

If you cannot confirm all three, apply the fix. If fixing would break the workflow and you cannot confirm all three, stop and report the finding — do not suppress.

- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 # zizmor: ignore[artipacked] -- credentials needed for git push

bot-conditions — Spoofable Bot Actor Check

Using github.actor == 'dependabot[bot]' alone in job conditions is spoofable.

Fix (always): Use a dual check: github.actor validates who triggered the current event, github.event.pull_request.user.login validates who owns the PR. Both together prevent a human-triggered event from re-entering the approve/merge path. Suppress the zizmor finding with a comment explaining the dual check is intentional.

# BEFORE (spoofable)
if: github.actor == 'dependabot[bot]'

# AFTER (dual check)
if: github.actor == 'dependabot[bot]' && github.event.pull_request.user.login == 'dependabot[bot]' # zizmor: ignore[bot-conditions] -- dual check: actor validates current trigger, user.login validates PR origin

Note: --fix=all will replace github.actor with github.event.pull_request.user.login. Revert the auto-fix and apply the dual check manually instead.

cache-poisoning — Cache Poisoning in Release Workflows

zizmor warns when setup actions (e.g., setup-go, setup-ruby, setup-node) enable caching in workflows triggered by tags or workflow_dispatch, since a poisoned cache from a PR could theoretically affect the release build.

WARNING: --fix=all will disable caching for these findings. Almost always revert these auto-fixes and suppress instead.

Suppress (default). GitHub Actions caches are isolated by branch. A pull_request workflow from a fork cannot write to the cache used by a tag-push or workflow_dispatch release workflow. The cache-poisoning attack requires an actor who already has push access to the default branch — and if they have that, they can modify the release workflow directly.

This applies even when the cached dependencies are used to build the release artifact, because the cache isolation makes the poisoning vector impractical.

Suppress only if:

• The workflow uses the default cache keys from setup actions (e.g., setup-go, setup-ruby,

setup-node), which are keyed by lockfile hash and branch. This is the common case.

Do NOT suppress if:

• The workflow uses actions/cache with a custom key: that is shared across branches or

includes attacker-controllable values (e.g., PR number, branch name from a fork). In this case, stop and report the finding.

The suppression comment should explain why it's safe in this specific case. Examples:

# Cache used for testing, not release artifact generation:
- uses: ruby/setup-ruby@... # zizmor: ignore[cache-poisoning] -- cached deps are for testing, not release artifact generation

# Cache used for release build, but branch-isolated so fork PRs can't poison it:
- uses: actions/setup-go@... # zizmor: ignore[cache-poisoning] -- cache is branch-isolated; fork PRs cannot write to this cache

dangerous-triggers — Dangerous Workflow Triggers

zizmor flags pull_request_target and workflow_run triggers. Both execute in the target repository's context (with write permissions and access to secrets) while remaining triggerable by external forks. Even workflows that don't explicitly check out PR code can be vulnerable to indirect execution vectors (argument injection, environment injection via LD_PRELOAD, GITHUB_ENV manipulation, etc.).

Fix (preferred):

• Replace workflow_run with workflow_call (convert to a reusable workflow)
• Replace pull_request_target with pull_request unless write permissions are required
• If pull_request_target is necessary, never check out or run PR-controlled code

Suppress only if ALL of these are true: 1. The workflow requires write access to the PR (e.g., labeling, commenting, gating) or needs to run after another workflow completes 2. The workflow does NOT check out the PR's head ref (actions/checkout with ref: ${{ github.event.pull_request.head.sha }} or similar) 3. The workflow does NOT run any code from the PR (no run: steps that execute checked-out files, no build/test steps) 4. The workflow does NOT pass attacker-controllable values into GITHUB_ENV, GITHUB_PATH, or GITHUB_OUTPUT 5. For workflow_run: you have confirmed it cannot be replaced with workflow_call

If you cannot confirm all applicable criteria, do NOT suppress. If fixing would break the workflow and you cannot confirm all criteria, stop and report the finding — do not suppress or fix.

on:
  pull_request_target: # zizmor: ignore[dangerous-triggers] -- required for write access to PRs from forks; workflow only runs trusted actions, no PR code is checked out or executed

dependabot-cooldown — Missing Cooldown on Dependabot Ecosystems

zizmor warns when dependabot ecosystem entries lack a cooldown period.

Fix (always): Add cooldown to every ecosystem entry in .github/dependabot.yml.

For real package ecosystems (bundler, npm, gomod, gradle, pip, etc.), use semver-granular cooldowns so low-risk patches flow faster while major bumps get more soak time:

cooldown:
  semver-major-days: 7
  semver-minor-days: 3
  semver-patch-days: 2

For github-actions, semver-granular keys are not supported. Use the default cooldown:

cooldown:
  default-days: 7

dependabot-execution — Insecure External Code Execution

Dependabot's insecure-external-code-execution: allow lets package managers run arbitrary code during dependency resolution.

Fix (if possible): Remove insecure-external-code-execution: allow.

Suppress only if ALL of these are true: 1. The package ecosystem requires code execution to resolve dependencies (e.g., Bundler with private gem sources that use custom source blocks in the Gemfile) 2. You have confirmed that removing allow causes dependency resolution to fail 3. The private registry is trusted (e.g., an internal GitHub Packages registry)

If you cannot confirm all three, apply the fix. If fixing would break dependency resolution and you cannot confirm all three, stop and report the finding — do not suppress.

insecure-external-code-execution: allow # zizmor: ignore[dependabot-execution] -- required for Bundler to resolve gems from the private github-basecamp registry

excessive-permissions — Overly Broad Permissions

Top-level permissions: grants those permissions to ALL jobs, violating least privilege.

Fix (always): Replace the workflow-level permissions: block with permissions: {} (deny all) and move permissions down to each individual job. The permissions: {} ensures every job starts with zero permissions, so any job that forgets to declare its own permissions will fail safe rather than inheriting broad defaults.

# BEFORE (too broad)
permissions:
  contents: read
  packages: write
  id-token: write
  attestations: write

jobs:
  build:
    ...
  merge:
    ...

# AFTER (deny-all at workflow level, scoped per job)
permissions: {}

jobs:
  build:
    permissions:
      contents: read
      packages: write
      id-token: write
      attestations: write
    ...
  merge:
    permissions:
      packages: write
      id-token: write
    ...

How to determine which permissions each job needs — DO NOT GUESS:

1. Start from the existing top-level permissions: block — that's the universe of permissions to distribute 2. For each job, identify which actions it uses 3. For each action, check the permission mappings in `references/permission-mappings.md`. If the action is not in that file, you MUST fetch its README on GitHub and read the documented permission requirements before proceeding. 4. Assign only the permissions each job actually needs 5. Don't invent permissions that weren't in the original block

After researching a new action's permissions, add it to `references/permission-mappings.md`.

Reusable workflows (`uses: ./.github/workflows/...`): Caller jobs that invoke reusable workflows must specify permissions explicitly. Reusable workflows inherit the caller job's permissions, and permissions can only be maintained or reduced through the chain — never elevated. When you set permissions: {} at the workflow level, every job (including reusable workflow calls) starts with zero permissions and must declare what it needs.

secrets-outside-env — Secrets Used Without GitHub Environment

zizmor flags jobs that use secrets.* (other than secrets.GITHUB_TOKEN) without an environment: declaration. Org/repo-level secrets are available to any workflow run, including from forks. Environment-scoped secrets are only available to jobs targeting that environment, providing an additional access control layer.

Fix (preferred): Add an environment: declaration to the job and move the secrets into that environment's secret store (removing them from repo/org-wide secrets).

# BEFORE (flagged)
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - run: ./deploy.sh
        env:
          API_KEY: ${{ secrets.API_KEY }}

# AFTER (fixed)
jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production
    steps:
      - run: ./deploy.sh
        env:
          API_KEY: ${{ secrets.API_KEY }}

Suppress only if ALL of these are true: 1. The job genuinely needs a non-GITHUB_TOKEN secret (not just a misconfiguration) 2. Adding an environment: declaration would break the workflow (e.g., environment protection rules would block PR-triggered runs that need the secret) 3. The secret is not exposed to untrusted code (e.g., not passed to a step that runs PR-submitted code)

If you cannot confirm all three, apply the fix. If the situation is ambiguous, stop and report the finding — do not suppress or fix.

jobs:
  test:
    runs-on: ubuntu-latest # zizmor: ignore[secrets-outside-env] -- API key needed in PR test runs; environment protection would block CI

superfluous-actions — Action Can Be Replaced With Inline Code

zizmor suggests replacing certain actions with equivalent inline shell commands.

Suppress (always): Never replace an existing action with inline code. Actions are more readable, maintainable, and receive upstream security fixes automatically. Suppress with a note to consider removal in the future.

- uses: softprops/action-gh-release@... # zizmor: ignore[superfluous-actions] -- consider removal

template-injection — Expression Injection in run: Blocks

Using ${{ }} directly in run: scripts allows attackers to inject shell commands via crafted PR titles, branch names, etc.

Fix (always): Pass expressions through env: vars. Never use ${{ }} directly in run:.

# BEFORE (vulnerable)
- run: |
    tags="${{ steps.meta.outputs.tags }}"
    echo "$tags"

# AFTER (safe)
- env:
    TAGS: ${{ steps.meta.outputs.tags }}
  run: |
    tags="$TAGS"
    echo "$tags"

This applies to ALL expressions in run: blocks, including github.event.pull_request.title, steps.*.outputs.*, inputs.*, etc. There is no valid reason to suppress this rule.

unpinned-images — Container Images Not Pinned to Digest

zizmor flags container images in services: or container: blocks that use a tag without a SHA256 digest. Tags are mutable — a compromised registry could serve different content under the same tag.

Suppress (default). Determining the correct digest for a container image is nontrivial (multi-arch manifests, registry-specific behavior, digest instability across rebuilds). Suppress with a reason.

image: myorg/myimage:1.0.0 # zizmor: ignore[unpinned-images] -- version tag is fine for service containers