GitHub Actions makes automation easy to copy, but a workflow can also import trust from every action it runs. A tag such as @v4 is convenient; it is not an immutable identity. If the referenced action changes later, the same workflow file can execute different code. GitHub’s own secure-use reference recommends pinning actions to a full-length commit SHA when you need an immutable release.
What an immutable action pin actually changes
An action reference has two useful properties: readability for humans and stability for automation. A version tag is readable, but the tag can move. A full commit SHA identifies one repository state, so a later tag change does not silently change the code your runner downloads. This is a supply-chain control, not a guarantee that the pinned commit is safe.
Use the official GitHub documentation as the policy baseline: GitHub Secure use reference. It states that pinning an action to a full-length commit SHA is currently the only way to use an action as an immutable release. GitHub also recommends reviewing the action’s source and considering whether it is maintained and trusted for your workflow.
Step 1: inventory every executable action
Start with .github/workflows/ and inspect every uses: entry. Include reusable workflows, composite actions, release automation, code scanning, checkout, upload, cache, and third-party setup actions. Do not stop at the main branch: review pull requests that modify workflow files and any shared workflow repository your organization consumes.
- Record the repository, referenced ref, current commit SHA, and the job that calls it.
- Mark whether the action receives secrets, write permissions, cloud credentials, or an artifact path.
- Separate GitHub-owned actions from third-party actions; provenance and maintenance evidence are different.
- Flag local actions such as
./.github/actions/buildfor code review even though they do not use a remote ref.
Step 2: replace movable refs with reviewed SHAs
For each remote action, resolve the intended release to its full 40-character commit SHA using the action repository and release information. Review the commit in the provider’s repository, then replace the movable ref. Keep a short comment with the human-readable version so maintenance remains understandable.
# Example format only; verify the SHA against the action repository before use
uses: actions/checkout@<40-character-reviewed-commit-sha> # vX.Y.Z
The example intentionally does not supply a made-up hash. A pin is useful only when the value was independently verified against the exact action release you intend to run. Treat a tag, branch, or abbreviated SHA as a review exception that needs a documented reason.
Step 3: review permissions and trust boundaries
Immutable pins reduce ref substitution risk, but they do not constrain what a workflow may do. Read the workflow’s permissions: block and grant the minimum required access. Prefer read-only defaults where possible, then add a narrowly scoped permission for the job that needs it. Review pull_request_target, untrusted fork inputs, checkout behavior, scripts that interpolate issue or pull-request text, and jobs that run on self-hosted runners.
GitHub’s security hardening guidance discusses protecting the GITHUB_TOKEN, avoiding script injection, and separating untrusted input from privileged execution. A workflow can be pinned and still be dangerous if it checks out attacker-controlled code into a privileged job.
Step 4: define an update and exception workflow
SHA pins create an explicit maintenance task. Decide who reviews updates, how release notes are checked, and how the old SHA is retained in the pull request diff. Dependabot or another update tool can propose changes, but automation should not be the only approval for actions with repository write access or production credentials.
| Review item | Evidence to keep | Decision |
|---|---|---|
| Action identity | Full SHA and readable release comment | Accept or replace |
| Scope | Job permissions and secret access | Minimize or isolate |
| Change provenance | Release notes, commit, maintainer history | Approve, investigate, or hold |
| Runtime boundary | Runner type and untrusted-input path | Use isolation or redesign |
If a team cannot verify a referenced commit, keep the workflow in a review state rather than claiming that the action is safe. Documented means the provider describes the behavior; tested means your own controlled run exercised it; inferred means your conclusion comes from configuration or source inspection. These labels should not be mixed.
Pull-request checklist
- Every remote
uses:reference is a full 40-character SHA or has a written exception. - The SHA maps to the intended release and the mapping is recorded in the review.
- Workflow permissions are no broader than the job requires.
- Secrets and write tokens are unavailable to untrusted code paths unless the boundary is deliberate and reviewed.
- Shell commands do not interpolate attacker-controlled titles, labels, comments, or branch names without safe handling.
- Self-hosted runners are isolated from sensitive networks and are maintained according to the organization’s runner policy.
- The resulting check is documented as tested, documented, inferred, or vendor-claimed.
FAQ: are SHA pins enough?
Do SHA pins prove an action is secure?
No. They make the referenced revision stable. You still need source review, least-privilege permissions, safe handling of untrusted input, and an appropriate runner boundary.
Should every action use the same approval threshold?
No. A formatting action with read-only access and a deployment action with cloud credentials have different blast radii. Apply stricter review to privileged jobs and reusable workflows.
Where does a local change review fit?
Use a local change-review gate to inspect the diff, workflow permissions, and trust-boundary changes before merge. The AI Change Firewall is designed for local intent-bound review of risky changes; it does not replace GitHub’s documentation or your organization’s approval process.
Next step
For a lightweight starting point, download the free AI code review checklist. For a broader comparison of local review options, use the single CodeRiskTools comparison page. Re-run this inventory whenever a workflow adds an action, changes permissions, or introduces a new runner boundary.
