Pinning Actions by Commit SHA

A static site's build pipeline is small, but it runs with real power: it can push to the repository, publish to the production domain and read deploy credentials. Most of that pipeline is other people's code — actions for checking out code, setting up Node or Hugo, caching, deploying, commenting on pull requests — referenced with a tag like @v4. Tags can be moved. In the March 2025 compromise of the popular tj-actions/changed-files action, an attacker repointed its tags to a commit that printed CI secrets into workflow logs, and every workflow referencing the action by tag ran that code on its next run. Workflows pinned to a full commit SHA did not.

This guide pins every action in a set of static site workflows to full commit SHAs, keeps the pins current with Renovate, enforces pinning with organization policy, and adds the other controls that limit what a compromised action could do. It is part of GitHub Actions for Automated SSG Builds, and complements Securing Deploy Credentials with GitHub OIDC.

Prerequisites

• Workflow files for building and deploying static sites.
• Renovate (or Dependabot) enabled on the repositories.
• Organization admin access for Actions policies.

Why Tags Are Not Enough

A reference like uses: peaceiris/actions-gh-pages@v4 resolves the tag v4 at run time. Maintainers move major-version tags on every release so users get fixes automatically — which is exactly the property an attacker exploits. A reference by SHA, uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e, resolves to one immutable commit. Even if the repository is compromised and every tag moved, the pinned workflow runs the same code it always did.

Pinning does not help if the pinned commit was already malicious, or if the action downloads and runs further code at run time (a Docker image by tag, a script fetched from a URL). It removes the most common and most damaging attack path: the silent change of what a trusted reference points to.

Step 1: Pin Every Action

Replace each tag with the commit SHA it currently points to, keeping the version as a comment so humans and bots know what it is:

# illustrative SHAs: resolve the current ones for your versions with pinact or ratchet
steps:
  - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683        # v4.2.2
  - uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af      # v4.1.0
  - uses: actions/cache@1bd1e32a3bdc45362d1e726936510720a7c30a57           # v4.2.0
  - uses: peaceiris/actions-hugo@75d2e84710de30f6ff7268e08f310b60ef14033f   # v3.0.0
  - uses: cloudflare/wrangler-action@6d58852c35a27e6034745c5d0bc373d739014f7f # v3.13.0

Tools do the lookup: pinact run rewrites a whole .github/workflows directory, and ratchet pin does the same with its own comment format. For reusable workflows and composite actions from your own organization, pin by SHA too, or at least by an immutable release tag, as discussed in Reusable Workflows for SSG Builds.

Across the organization's fourteen site repositories, pinning touched 212 uses: lines referencing 23 distinct actions.

Step 2: Keep Pins Current Automatically

Pins without updates become stale — missing security fixes, then breaking when GitHub deprecates an old Node runtime for actions. Renovate updates SHA pins and their comments together:

{
  "extends": ["config:recommended", "helpers:pinGitHubActionDigests"],
  "packageRules": [
    { "matchManagers": ["github-actions"], "groupName": "GitHub Actions", "schedule": ["before 6am on monday"] },
    { "matchManagers": ["github-actions"], "matchUpdateTypes": ["minor", "patch", "digest"], "automerge": true, "minimumReleaseAge": "3 days" }
  ]
}

helpers:pinGitHubActionDigests pins any unpinned action it finds. Minor and patch updates are grouped weekly and auto-merged after passing CI, but only once a release is three days old (minimumReleaseAge), which gives the community time to notice a compromised release before it reaches these repositories. Major updates get a normal review. Dependabot supports SHA pins with version comments as well, with fewer grouping options.

Step 3: Enforce It With Organization Policy

Pinning by convention erodes; policy holds. In the organization's Actions settings:

• Allow actions: "Allow enterprise and select non-enterprise actions", with GitHub-created actions, verified creators, and an explicit allowlist (peaceiris/*, cloudflare/wrangler-action@*, DavidAnson/markdownlint-cli2-action@*).
• Require actions to be pinned to a full-length commit SHA: enabled. Workflows referencing an allowed action by tag then fail to start, with a clear error.

The policy found three workflows in older repositories that had been missed by the initial pinning pass; they failed on their next run and were fixed within the day.

Step 4: Limit What Any Action Can Do

Pinning reduces the chance of running malicious code; least privilege limits the damage if it happens anyway:

permissions:
  contents: read          # workflow default: read-only
jobs:
  deploy:
    permissions:
      contents: read
      id-token: write       # OIDC for the deploy, no long-lived token
      deployments: write

Set permissions at the top of every workflow so the default GITHUB_TOKEN is read-only, and grant more per job. Pass secrets only to the steps that use them (env: on the step, not the job). Use OIDC for deploy credentials, so there is no long-lived secret for a compromised step to exfiltrate. And never run pull_request_target workflows that check out and build untrusted pull request code with secrets available.

Reviewing Action Updates

Automated update pull requests are only as safe as the review they get. For major updates and for any action that receives secrets or deploy permissions, the review checklist is short: read the release notes, open the diff between the old and new SHA on GitHub (the Renovate pull request links to it), look for new network calls, new dependencies, or changes to how inputs such as tokens are handled, and check that the release was made by the usual maintainers. For the handful of actions that touch deploy credentials, the team goes a step further and considers replacing the action with a few lines of shell calling the vendor's CLI directly — wrangler deploy instead of a wrapper action, for instance — which removes one third party from the chain entirely. Two of the nine allowlisted third-party actions were replaced that way in the first quarter.

GitHub's dependency graph also lists Actions as dependencies, and security advisories for actions appear as Dependabot alerts. Enabling alerts on every site repository means a published advisory for a pinned action produces a notification even before an update is available, so the team can decide whether to disable the affected workflow temporarily.

Measured Impact

Pitfalls & Rollback

• Short SHAs. Only full 40-character SHAs are immutable references; policy requires them.
• Pinning without updating. Stale actions break when runtimes are deprecated; automate updates.
• Docker-based actions pulling :latest. The action's code is pinned but its image is not; prefer actions that pin their images by digest.
• Forgetting reusable workflows and composite actions. Pin those references too.
• Rollback: pins are plain text in workflow files; the policy can be relaxed in organization settings if a pinned version must be bypassed urgently.

Conclusion

Tags on third-party actions are a promise from someone else that can be broken without your knowledge. Pin every action to a full commit SHA with a version comment, let Renovate or Dependabot update the pins with a short release-age delay, enforce pinning and an allowlist with organization policy, and keep permissions and credentials minimal so any compromise is contained. For static site pipelines — small, but holding the keys to production — it is a few hours of work with an outsized payoff.

FAQ

Why pin actions by commit SHA instead of a version tag?

Tags are mutable. Whoever controls an action's repository can move a tag such as v4 to a different commit, including a malicious one, and every workflow using that tag runs the new code on its next run. A full-length commit SHA refers to one exact snapshot that cannot be changed.

Do I need to pin GitHub's own actions such as actions/checkout?

The risk is lower, but pinning everything is simpler to enforce than maintaining exceptions, and the organization policy that requires SHA pinning applies to all actions. Many teams pin everything and let automation keep the pins current.

How do I keep pinned actions up to date?

Use Renovate or Dependabot, which understand SHA pins with a version comment, such as a trailing comment naming v4.2.0. They open pull requests that update both the SHA and the comment when a new version is released.

What else reduces supply-chain risk in workflows?

Restrict allowed actions to GitHub, verified creators and an explicit allowlist in organization settings, grant GITHUB_TOKEN the minimum permissions, avoid passing secrets to steps that do not need them, and use short-lived OIDC credentials for deploys.

Related

• Parent: GitHub Actions for Automated SSG Builds — the pipelines being hardened.
• Securing Deploy Credentials with GitHub OIDC — removing long-lived secrets.
• Auditing npm Dependencies in SSG Pipelines — the site's own dependencies.
• Reusable Workflows for SSG Builds — pin once in a shared workflow.
• Security Headers and Hardening for Static Sites — the wider security picture.