Secure GitHub Actions

Enforces supply chain hardening rules for GitHub Actions workflows. Every rule below addresses a real vulnerability class found in security audits of production workflows.

When to Use

• Writing a new .github/workflows/*.yml file
• Modifying an existing workflow
• Reviewing a PR that touches workflow files
• Adding a secret, action reference, or reusable workflow call
• Configuring claude-code-action or claude-code-base-action

When NOT to Use This Skill

This skill is specifically for GitHub Actions workflow YAML files. If you reach it but the actual task is one of the below, step aside: say in a single line that the rules here only apply to .github/workflows/*.yml edits and continue with the real task. Do not run the audit grep commands or the pre-PR checklist on unrelated code.

• Other CI providers — any non-GitHub-Actions CI config (a Buildkite pipeline, a CircleCI/GitLab/Jenkins config, etc.) — use that provider's own tooling
• Test / e2e harness setup (Playwright, Cypress, or any framework) that does not edit a workflow YAML
• Dependency or lockfile pinning in a package manifest of any language (package.json, Gemfile, pom.xml, go.mod, requirements.txt, Cargo.toml, …) — even though supply-chain–adjacent, the rules below are about workflow YAML idioms
• Generic CI investigation with no workflow file change in scope
• Package supply-chain questions for any ecosystem (npm, RubyGems, Maven, Go modules, PyPI, crates, …) — use a package supply-chain scanner

If a workflow file is also in scope alongside one of the above, apply the rules to the workflow file and step aside for the rest.

The Rules

Rules 1-11: All Repositories

Rule 1: No ${{ }} in run: blocks

Never interpolate any ${{ }} expression directly in a run: block — route everything through env: variables. This applies to all expressions, not just attacker-controlled ones:

• Attacker-controlled values (github.event.*, inputs.*) — shell injection risk
• Secrets (secrets.*) — leak via set -x, shell errors, and process listings
• Context values (github.repository, github.run_id, steps.*.outputs.*) — trains bad habits, zizmor flags them, and any future refactor that introduces attacker input into the same block inherits the anti-pattern

# VULNERABLE — attacker-controlled title executes as shell
run: |
  TITLE="${{ github.event.issue.title }}"

# ALSO WRONG — "not attacker-controlled" is not an excuse
run: |
  gh issue edit "${{ github.event.issue.number }}" --repo "${{ github.repository }}"
  curl -H "Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}" "$URL"

# SAFE — env vars are set before shell parses the script
env:
  ISSUE_TITLE: ${{ github.event.issue.title }}
  ISSUE_NUMBER: ${{ github.event.issue.number }}
  REPO: ${{ github.repository }}
  GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
  echo "$ISSUE_TITLE"
  gh issue edit "$ISSUE_NUMBER" --repo "$REPO"

Why: GitHub expands ${{ }} expressions via string interpolation before the shell sees the script. A malicious issue title like "; curl attacker.com; " breaks out of quotes and executes arbitrary commands. Env vars are injected as process environment, not text substitution, so shell metacharacters are inert.

Even "safe" values like github.repository or secrets.GITHUB_TOKEN should go through env: — secrets can leak via set -x or shell error messages, and allowing some ${{ }} in run: blocks trains the pattern as acceptable, leading to copy-paste injection bugs when the same block is extended with attacker-controlled values later.

Simple rule: if you see ${{ }} inside a run: block, it's wrong. Move it to env:.

Highest-risk expressions (attacker-controlled — shell injection):

• github.event.issue.title, .body
• github.event.comment.body
• github.event.pull_request.title, .body, .head.ref
• github.event.label.name
• github.event.review.body
• inputs.* (workflow_dispatch, workflow_call)

Still wrong in run: blocks (not attacker-controlled, but banned):

• secrets.* — leak risk via shell diagnostics
• github.repository, github.run_id, github.server_url
• steps.*.outputs.*, needs.*.outputs.*, job.status
• github.event.issue.number, github.event.pull_request.number

Safe in with: blocks (YAML context, no shell): ${{ }} in action with: inputs is safe from shell injection, but still a prompt injection vector if passed to AI tools.

Rule 2: No secrets: inherit

Always use explicit secrets: mapping when calling reusable workflows. List exactly which secrets the called workflow needs.

# VULNERABLE — exposes ALL repo secrets to the called workflow
jobs:
  notify:
    uses: your-org/shared-workflows/.github/workflows/notify.yml@9f8e7d6c5b4a39281706f5e4d3c2b1a09f8e7d6c # v2.3.1
    secrets: inherit

# SAFE — only passes what's needed
jobs:
  notify:
    uses: your-org/shared-workflows/.github/workflows/notify.yml@9f8e7d6c5b4a39281706f5e4d3c2b1a09f8e7d6c # v2.3.1
    secrets:
      SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}

Why: secrets: inherit passes every secret the caller has access to. If the called workflow is compromised, every secret is exfiltrated. This is a well-documented real-world exfiltration path — incidents have traced back to a single secrets: inherit repeated across many workflows.

Rule 3: SHA-pin all action references

Pin every uses: reference to a full commit SHA with a version comment.

# VULNERABLE — mutable tag, can change without notice
uses: actions/checkout@v4
uses: anthropics/claude-code-action@v1
uses: anthropics/claude-code-base-action@beta

# SAFE — immutable SHA with human-readable comment
uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
uses: anthropics/claude-code-action@ad30de060ff4bb30eaa7e07042e4aebacfae7dac # v1.0.29

How to resolve a SHA:

# For tags:
gh api repos/{owner}/{repo}/git/ref/tags/{tag} --jq '.object.sha'
# For branches:
gh api repos/{owner}/{repo}/git/ref/heads/{branch} --jq '.object.sha'

Why: Tags and branches are mutable. A compromised upstream repo can point @v1 to malicious code. SHAs are immutable — the only tamper-proof reference.

Rule 4: Trusted actions only

Restrict which actions can run in your org (Settings → Actions → Allow select actions). A tight allowlist is a strong supply-chain control. A good baseline:

• actions/*, github/* — GitHub first-party (org-level toggle)
• Your own org's actions (your-org/*)
• anthropics/* — Claude code actions, if used
• A short, explicitly-vetted list of third-party actions you actually depend on (e.g. ruby/setup-ruby, pnpm/action-setup) — each pinned by SHA

Anything not on the allowlist is blocked. Before adding a new third-party action, prefer gh CLI or actions/github-script over taking on a new dependency.

# Instead of a third-party action:
- run: gh issue comment "$ISSUE_NUMBER" --body "Processed by CI"
  env:
    GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    ISSUE_NUMBER: ${{ github.event.issue.number }}

Prefer native solutions over third-party actions

Before adding a third-party action — or widening the allowlist to permit one — ask whether the same behaviour is achievable with a few more lines of native code. If yes, use the native approach: it keeps the org's third-party action surface smaller, eliminates a SHA-pinning maintenance burden, and removes a supply chain attack vector entirely.

Native alternatives to reach for first:

# AVOID — third-party action for a trivial operation
- uses: dessant/label-actions@abc123 # v4
  # Requires config file + adds third-party dep to supply chain

# PREFER — same behaviour as two GitHub API calls in actions/github-script
- name: Re-add label and explain
  uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
  with:
    script: |
      await github.rest.issues.createComment({
        owner: context.repo.owner,
        repo: context.repo.repo,
        issue_number: context.issue.number,
        body: ':wave: This label is managed by CI.'
      });
      await github.rest.issues.addLabels({
        owner: context.repo.owner,
        repo: context.repo.repo,
        issue_number: context.issue.number,
        labels: ['protected-label']
      });

The bar for keeping a third-party action: the native equivalent would require significantly more code or is clearly not maintainable inline (e.g., complex multi-step setup actions like ruby/setup-ruby). "A few more lines" is not a reason to keep a dependency.

Rule 5: Always declare permissions:

Every workflow MUST have a top-level permissions: block with least privilege. Even when the org default is read-only, declaring permissions explicitly is defense in depth — org defaults can change, and explicit is self-documenting.

permissions:
  contents: read
  issues: write
  pull-requests: read

Only add permissions the workflow actually needs. Common mistakes:

• id-token: write when not using OIDC — remove it. Exception: reusable-workflow callers — if the job uses: a reusable workflow, do not strip id-token: write (or any scope) just because the caller's own steps don't reference it; the callee may need it. See "Reusable workflow callers: caller caps callee" in references/permission-scopes.md.
• contents: write when only reading — use read (same caller exception)
• Missing block entirely — defaults to repo-wide setting

Choosing or changing a scope? Read references/permission-scopes.md first. Load it before you add, remove, or narrow any scope — and before you conclude an existing one is unnecessary. In particular, load it when the workflow comments on PRs, manages labels, or edits PR metadata; when the job uses: a reusable workflow, whatever scopes the caller declares, including none; or when you are tempted to strip id-token: write because no step in front of you references OIDC.

It is a hard trigger rather than a "see also" because both failure modes it documents are silent. A clipped GITHUB_TOKEN scope 403s inside the callee while CI logs green; a clipped id-token: write fails at run creation with no logs at all. Neither is visible from the caller you are reading, so "the permissions block looks fine" is not a judgement you can reach without it.

Rule 6: No unpinned runtime dependencies

No npx @latest, no git clone at HEAD, no npm install without a lockfile.

# VULNERABLE
run: npx @modelcontextprotocol/server-github@latest
run: npx -y @sentry/mcp-server@latest
run: git clone https://github.com/org/repo.git && cd repo && npm install

# SAFE — pinned to exact version
run: npx @modelcontextprotocol/server-github@1.2.3
# SAFE — pinned to commit SHA with lockfile
env:
  REPO_SHA: "abc123def456"
run: |
  git clone https://github.com/org/repo.git
  cd repo
  git checkout "$REPO_SHA"
  npm ci

Common mistake: git clone --revision is not a valid git flag — it gets silently ignored, cloning HEAD instead of the pinned SHA. Use git clone followed by git checkout "$SHA". For shallow clones, use git fetch --depth 1 origin "$SHA" after init.

Why: @latest and HEAD are mutable references that resolve at runtime. A compromised package or repo delivers malicious code the next time the workflow runs.

Rule 7: Never checkout untrusted code with secrets

If using pull_request_target, never checkout the PR head in a job that has secrets. Split into two jobs:

jobs:
  # Job 1: Unprivileged — validates the PR
  validate:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    outputs:
      safe: ${{ steps.check.outputs.safe }}
    steps:
      - name: Validate via API (no checkout of PR code)
        id: check
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          # Validate using GitHub API only — never run PR code

  # Job 2: Privileged — acts on validated PR (never checks out PR code)
  act:
    needs: validate
    if: needs.validate.outputs.safe == 'true'
    runs-on: ubuntu-latest
    steps:
      - name: Label PR via API
        env:
          GH_TOKEN: ${{ secrets.ELEVATED_TOKEN }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
        run: gh pr edit "$PR_NUMBER" --add-label "validated"

Trusted script pattern (when you need both base code and PR history):

steps:
  - name: Checkout base branch (trusted code)
    uses: actions/checkout@SHA # pinned
  - name: Preserve trusted script
    run: cp script/security/scanner.rb /tmp/trusted_scanner.rb
  - name: Fetch PR head (for git history only)
    env:
      PR_NUMBER: ${{ github.event.issue.number }}
    run: |
      git fetch origin "pull/$PR_NUMBER/head"
      git checkout FETCH_HEAD
  - name: Run trusted script
    run: ruby /tmp/trusted_scanner.rb

Rule 8: No pull_request_target unless necessary

Prefer pull_request trigger. It runs in the context of the fork with no secrets access, which is safe by default.

pull_request_target grants secrets and write permissions to code triggered by a fork PR. If you must use it, document why in a YAML comment and follow the split-job pattern from Rule 7.

# SAFE default — use this
on:
  pull_request:
    types: [opened, synchronize]

# DANGEROUS — only if you need secrets for fork PRs, with documented justification
on:
  pull_request_target:  # Required because: [specific reason]
    types: [opened, synchronize]

Rule 9: Scope Claude/AI tool access when handling untrusted input

When using claude-code-action or claude-code-base-action on workflows that process untrusted input (issue bodies, PR diffs, external content), scope allowed_tools to limit blast radius from prompt injection.

# Higher risk — if the workflow processes untrusted input
with:
  allowed_tools: "Read,Write,Edit,Bash,Glob,Grep"

# Lower risk — scoped to specific CLI patterns
with:
  allowed_tools: "Read,Grep,Glob,Bash(gh issue:*),Bash(gh pr:*)"

Why: If Claude processes attacker-controlled content (issue bodies, PR diffs), prompt injection could lead to unintended command execution. Scoping Bash to specific patterns reduces the blast radius.

Rule 10: Actions creating or approving PRs

GitHub provides an org/repo setting — Allow GitHub Actions to create and approve pull requests — that is off by default, and turning it off is recommended: it closes a privilege-escalation path where a workflow self-approves or opens PRs. With it off, any workflow that tries to create or approve a PR fails with a permissions error.

If you keep it off (recommended), migrate workflows that create or approve PRs:

• PR approvals / creation → Use a dedicated GitHub App with narrowly-scoped permissions and policy enforcement, not the Actions GITHUB_TOKEN

Remove any gh pr review --approve, gh pr create, or equivalent API calls from workflow run: blocks when the setting is off. If reviewing a workflow that still contains PR creation or approval steps under that policy, flag it as a required migration.

Rule 11: Guard GITHUB_ENV and GITHUB_PATH from untrusted input

Never write attacker-controlled values to GITHUB_ENV or GITHUB_PATH. These files modify the environment for all subsequent steps in the job.

# VULNERABLE — attacker-controlled label written to GITHUB_ENV
run: |
  echo "LABEL=${{ github.event.label.name }}" >> $GITHUB_ENV

# VULNERABLE — untrusted step can poison PATH for later steps
run: echo "/tmp/attacker-bin" >> $GITHUB_PATH

# SAFE — use env: block, don't propagate to GITHUB_ENV
env:
  LABEL: ${{ github.event.label.name }}
run: |
  echo "Processing $LABEL"

Why: A compromised or attacker-influenced step can set LD_PRELOAD, inject malicious binaries into PATH, or override variables consumed by later steps. Unlike env: blocks (scoped to one step), GITHUB_ENV persists across all subsequent steps in the job.

Public Repository Rules (Rules 12-14)

Public repos enforce three extra rules on top of Rules 1-11. Before reviewing, detect repo visibility:

gh repo view --json visibility -q '.visibility'

If the result is PUBLIC, load references/public-repo-rules.md and enforce Rules 12-14 (LOTP / no secrets on fork PR builds, persist-credentials: false on checkout, and OIDC over long-lived cloud secrets) in addition to the all-repo rules above. Skip this reference for private repos — Rules 12-14 do not apply there.

Pre-PR Checklist

Run this against your workflow before submitting. Every item maps to a rule above.

[ ] No ${{ }} expressions of any kind in run: blocks (Rule 1)
[ ] No secrets: inherit — all secrets explicitly mapped (Rule 2)
[ ] Every uses: reference is SHA-pinned with version comment (Rule 3)
[ ] All actions are on the org allowlist (Rule 4)
[ ] Third-party actions replaced with native alternatives where feasible (Rule 4)
[ ] Top-level permissions: block with least privilege (Rule 5)
[ ] If calling a reusable workflow, caller permissions: grants at least every scope the callee declares (Rule 5)
[ ] Reusable-workflow caller: no scope stripped on "caller doesn't use it" reasoning — keep id-token: write (and others) the callee needs; stripping id-token: write causes startup_failure (Rule 5)
[ ] PR-commenting workflows keep pull-requests: write — scope mapped by target resource, not API namespace; existing write scopes not downgraded without checking the steps (Rule 5)
[ ] No npx @latest, git clone at HEAD, or npm install without lockfile (Rule 6)
[ ] If pull_request_target: no PR head checkout in jobs with secrets (Rule 7)
[ ] pull_request used instead of pull_request_target where possible (Rule 8)
[ ] Claude allowed_tools scoped if workflow processes untrusted input (Rule 9)
[ ] No PR creation or approval steps if the org setting is off — use a GitHub App (Rule 10)
[ ] No attacker-controlled values written to GITHUB_ENV or GITHUB_PATH (Rule 11)
[ ] (Public repos) No secrets in fork PR build jobs (Rule 12)
[ ] (Public repos) persist-credentials: false on checkout (Rule 13)
[ ] (Public repos) OIDC tokens over long-lived secrets for cloud auth (Rule 14)

Quick Audit Command

To scan an existing set of workflows for violations of the rules above, load references/audit-commands.md — it ships one command per rule (stray ${{ }} in run:, secrets: inherit, unpinned uses:, missing permissions:, unpinned npx, PR creation/approval, unscoped Claude Bash, GITHUB_ENV/GITHUB_PATH writes, missing persist-credentials).

Common Mistakes

Response Style

When applying these rules — reviewing a workflow, answering a question, or writing a new file — output the findings, not the process. This skill's body is long (twelve rules plus a pre-PR checklist); paraphrasing it back adds tokens and hides the verdict.

• Lead with the verdict or the diff. For a review: which rules are violated (by number) and where. For a new workflow: the corrected YAML. For a question: the answer.
• No narration of the review flow. Skip "Now I'll check each rule…", "Let me look at the run: blocks…", "The workflow uses…". If a rule is clean, do not name it; silence is the pass signal.
• No re-recitation of the rule text. Cite the rule by number ("Rule 1 violation: ${{ github.event.issue.title }} in run: at line 42"); do not paste the rule's explanation back from the body — the reader can see it here.
• Show corrected YAML, not prose about corrections. A three-line diff is a better fix than a paragraph describing one.
• One-line step-aside for out-of-scope tasks. When the task doesn't touch a workflow YAML (see "When NOT to Use This Skill"), say so in a single sentence and continue — do not walk through the checklist first.