pin GitHub Actions to specific commit SHAs

Oct 13, 2025 by wbrum.org 53 views

Pin GitHub Actions to Specific Commit SHAs Instead of Versions: A Guide to Improved Supply Chain Security

Why Pin to a Commit SHA?

In today's software development landscape, supply chain security is a top concern. One potential security risk arises from referencing version tags in GitHub Actions workflows. While this approach is convenient, it introduces a risk of breaking changes or malicious code in newer versions. To mitigate this risk, it's essential to pin GitHub Actions to specific commit SHAs. This ensures that the workflow only runs a verified version of the action, providing improved security, predictable builds, and auditability.

Steps to Complete This Task

1. Identify All Actions Using Version Tags

The first step is to review all GitHub Actions workflows under .github/workflows/. Identify any action referencing a version like actions/checkout@v4 or actions/setup-python@v5. This is crucial in understanding which actions need to be updated.

uses: actions/checkout@v4
uses: actions/setup-python@v5

2. Resolve the Commit SHA for Each Action

For each action, find the corresponding commit SHA for the current version. This can be done by visiting the action's repository on GitHub, going to the Releases section, and looking at the commit linked to the version tag. Alternatively, you can use the command:

gh api repos/{owner}/{repo}/git/refs/tags/{version}

Example:

gh api repos/actions/checkout/git/refs/tags/v4

3. Update the Workflow Files

Replace each version tag with its full commit SHA like this:

uses: actions/checkout@v4

becomes:

uses: actions/checkout@<full-commit-sha>

Example:

uses: actions/checkout@v4

→

uses: actions/checkout@8fdb40e56baf9c5dc24e3ab5bc2a91db65f39f21

Do this for all actions in all workflows.

4. Verify the Workflow Files

Run a test workflow (manually or via a PR) to ensure the pinned SHAs do not break any workflows. Double-check that each commit SHA corresponds to the latest tagged version that was already in use.

5. Document the Change

Optionally add a note to CONTRIBUTING.md (or equivalent) stating that:

All new GitHub Actions must use commit SHAs instead of version tags.
When updating an action, contributors should explicitly use the commit SHA from the latest release.

Example:

# Allowed:
uses: actions/checkout@8fdb40e56baf9c5dc24e3ab5bc2a91db65f39f21

# Not allowed:
uses: actions/checkout@v4

6. Automate SHA Pinning (Optional)

Consider adding a GitHub Action or Dependabot rule to automatically raise a PR when a new version is released, updating the pinned commit SHA. This will reduce manual work while ensuring secure, predictable builds.

Acceptance Criteria

All GitHub Actions in .github/workflows/ use commit SHAs instead of version tags.
A test workflow runs successfully after updating the SHAs.
Documentation (if applicable) includes guidance on pinning future actions to a commit SHA.
No action references a version like @v4 or @v5 without a specific commit.

Notes

This task is critical for improving the supply chain security of the project.
If you encounter any issues while resolving the commit SHAs, feel free to ask in the comments.
If desired, a follow-up task can be created to implement an automated updater for pinned SHAs.

By following these steps and guidelines, you can ensure that your GitHub Actions workflows are secure, predictable, and auditable. Remember to document the change and consider automating SHA pinning for future updates.
Pin GitHub Actions to Specific Commit SHAs Instead of Versions: A Q&A Guide

Q: Why is it necessary to pin GitHub Actions to specific commit SHAs?

A: Pinning GitHub Actions to specific commit SHAs is necessary to improve supply chain security. By locking the action to a specific, verified version, you prevent potential security risks associated with referencing version tags. This ensures that the workflow only runs a verified version of the action, providing improved security, predictable builds, and auditability.

Q: How do I identify all actions using version tags in my GitHub Actions workflows?

A: To identify all actions using version tags, review all GitHub Actions workflows under .github/workflows/. Look for any action referencing a version like actions/checkout@v4 or actions/setup-python@v5. This is crucial in understanding which actions need to be updated.

Q: How do I resolve the commit SHA for each action?

A: To resolve the commit SHA for each action, visit the action's repository on GitHub, go to the Releases section, and look at the commit linked to the version tag. Alternatively, you can use the command:

gh api repos/{owner}/{repo}/git/refs/tags/{version}

Example:

gh api repos/actions/checkout/git/refs/tags/v4

Q: How do I update the workflow files to use commit SHAs instead of version tags?

A: To update the workflow files, replace each version tag with its full commit SHA like this:

uses: actions/checkout@v4

becomes:

uses: actions/checkout@<full-commit-sha>

Example:

uses: actions/checkout@v4

→

uses: actions/checkout@8fdb40e56baf9c5dc24e3ab5bc2a91db65f39f21

Do this for all actions in all workflows.

Q: How do I verify that the pinned SHAs do not break any workflows?

A: Run a test workflow (manually or via a PR) to ensure the pinned SHAs do not break any workflows. Double-check that each commit SHA corresponds to the latest tagged version that was already in use.

Q: Do I need to document the change?

A: Yes, it's recommended to document the change by adding a note to CONTRIBUTING.md (or equivalent) stating that:

All new GitHub Actions must use commit SHAs instead of version tags.
When updating an action, contributors should explicitly use the commit SHA from the latest release.

Example:

# Allowed:
uses: actions/checkout@8fdb40e56baf9c5dc24e3ab5bc2a91db65f39f21

# Not allowed:
uses: actions/checkout@v4

Q: Can I automate SHA pinning for future updates?

A: Yes, consider adding a GitHub Action or Dependabot rule to automatically raise a PR when a new version is released, updating the pinned commit SHA. This will reduce manual work while ensuring secure, predictable builds.

Q: What are the acceptance criteria for this task?

A: The acceptance criteria for this task are:

All GitHub Actions in .github/workflows/ use commit SHAs instead of version tags.
A test workflow runs successfully after updating the SHAs.
Documentation (if applicable) includes guidance on pinning future actions to a commit SHA.
No action references a version like @v4 or @v5 without a specific commit.

Q: What are the notes for this task?

A: The notes for this task are:

This task is critical for improving the supply chain security of the project.
If you encounter any issues while resolving the commit SHAs, feel free to ask in the comments.
If desired, a follow-up task can be created to implement an automated updater for pinned SHAs.