Pinning to commit SHA — the only safe reference

Pinning to a full 40-character commit SHA turns the action reference from a pointer into a content address. The runner downloads exactly the bytes your team reviewed at pin time; the maintainer cannot move the SHA, cannot retroactively change the commit, and cannot force your workflow to execute a different version. This is the only safe form of action reference.

The three reference forms

GitHub Actions accepts three forms:

# Mutable reference - tag can move
- uses: actions/checkout@v4
# Mutable reference - branch tip moves
- uses: actions/checkout@main
# Immutable reference - SHA is content hash
- uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11

A tag resolves at job start; the tag can move between runs. A branch tip moves on every commit. A commit SHA does not move.

flowchart LR
    A["Tag v4"] --> B["Pointer"]
    B --> C["Commit A1"]
    B -. "force-push" .-> D["Commit A2"]
    E["SHA b4ffde65..."] --> F["Bytes B1"]
    F -. "immutable" .-> G["Same bytes forever"]

Why a full 40-character SHA

The runner accepts abbreviated SHAs, but the documentation recommends the full 40-character form. Two reasons: collision resistance (a 7-char SHA has ~268M values; a 40-char SHA has 2^160) and audit clarity (a 40-char SHA is unambiguous).

# Resolve a tag to a full SHA locally
git ls-remote https://github.com/actions/checkout.git refs/tags/v4
# -> ${ACTIONS_CHECKOUT_SHA}  refs/tags/v4

# Confirm the SHA is exactly 40 hex characters
echo -n "${ACTIONS_CHECKOUT_SHA}" | wc -c
# -> 40

The pinning workflow

Pinning is a deliberate operation performed under review. Five steps:

1. Identify the action. Confirm maintainer, repo, and intended version.
2. Resolve the version. Resolve the tag or branch tip to its commit SHA.
3. Review the action at the SHA. Read action.yml, index.js or Dockerfile, and package.json. Confirm the action pins its own dependencies and the maintainer is responsive.
4. Pin the workflow. Update the workflow file with the SHA. The PR contains the pin, the resolved SHA, the review notes, and a link to the upstream release.
5. Subscribe to advisories. Configure GitHub Watch on the action’s repository.

# Pinned reference - safe
- uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
# Pinned reference - safe, composite action
- uses: github/codeql-action/analyze@ff0a06e83cb2de871e5bfc9e9058eb2a83dff1c7

Re-pinning as a deliberate upgrade

A pin is a freeze. The freeze must end deliberately. Three signals trigger a re-pin: security advisory, upstream API change, or routine refresh. Dependabot can automate the resolution step — it opens a PR updating the pin — but the team still reviews the PR. The automatic part is the SHA resolution; the review part is not.

What pinning does not close

Pinning does not close:

• The abandoned-action risk. Pinned bytes still depend on the same vulnerable transitive packages (LXVI-04).
• The transitive dependency drift. The action’s own node_modules may be unpinned.
• The history-rewrite attack. Force-pushing changes the SHA a team is following.

Pinning is necessary. Pinning is not sufficient. The allowlist covered in the next lesson is the policy layer that closes the gaps pinning leaves open.

Production discipline

1. Pin every third-party action to a full 40-character SHA. No exceptions. No tags. No branches.
2. Verify the SHA length. echo -n "$ACTIONS_CHECKOUT_SHA" | wc -c must return 40.
3. Resolve the SHA at pin time. Document the tag, the upstream release, and the resolved SHA in the PR.
4. Review the action at the SHA before pinning.
5. Re-pin deliberately. A new pin is a new pull request.

Cross-course references

• Git, CI/CD & GitOps — Part LXVI-02 (Tag-Swap Attack) establishes the mutable-reference risk pinning closes.
• Git, CI/CD & GitOps — Part LXV-05 (Artifact Trust) covers the content-addressing model pinning relies on.
• Git, CI/CD & GitOps — Part LXVI-06 (Allowlisting) covers the policy layer pinning leaves open.

Quiz