GitHub Actions workflows depend on actions from repositories such as checkout, setup-node, upload-artifact, cloud deployment tools, and many third-party actions.
A workflow might look simple:
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
- run: npm ci
- run: npm test
This is easy to read and maintain, but the workflow is not necessarily tied to one exact version of the action code.
For security-sensitive CI pipelines, that distinction matters.
An action referenced by a mutable tag can change later without the workflow file itself changing. Pinning an action to an immutable Git commit gives the workflow a fixed dependency.
The challenge is maintenance.
If every action is pinned to a commit and nobody tracks updates, the workflow can become difficult to maintain. Security fixes and useful action updates may remain unnoticed for months.
The practical goal is therefore not simply to pin everything and forget about it. The goal is to make action versions predictable while keeping updates manageable.
What Action Pinning Means
Consider this workflow reference:
- uses: actions/checkout@v4
The workflow is using the v4 tag.
A tag is easier for humans to understand, but the tag can move to another commit.
A commit SHA is different:
- uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608
The reference points to one specific Git commit.
Conceptually:
Tag
|
+-- Can point to a different commit later
Commit SHA
|
+-- Points to one specific commit
That makes the workflow more predictable.
Why Pinning Matters in CI
GitHub Actions workflows often have access to resources that normal application code does not.
Depending on the workflow, an action may have access to:
Repository contents
Build artifacts
Cloud credentials
Deployment credentials
Package registries
Pull request information
Environment variables
Secrets
This makes the CI pipeline an important part of the application's security boundary.
If an action changes unexpectedly, the consequences can be more serious than an ordinary dependency update.
Pinning reduces that uncertainty.
Tags Are Convenient but Mutable
A version tag such as:
- uses: actions/checkout@v4
is convenient because developers immediately understand what it means.
However, the tag does not identify one immutable piece of code.
A tag can be updated by the action maintainer to point to a newer commit.
That is useful for receiving updates, but it also means the workflow can execute different code over time without a change to your repository.
This is the tradeoff:
Reference | Maintenance | Reproducibility | Security Control |
|---|
Branch | Easy | Low | Weak |
Major tag | Easy | Medium | Moderate |
Minor tag | Moderate | Better | Moderate |
Commit SHA | More work | High | Strong |
The exact security decision should match the organization's requirements.
Pin Actions to Full Commit SHAs
When strong supply-chain controls are required, use a full commit SHA.
For example:
- uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608
Avoid using a shortened SHA.
A full SHA makes the reference unambiguous.
The same approach can be used for third-party actions:
- uses: some-org/example-action@<full-commit-sha>
The SHA should come from a trusted source.
Do not copy a commit hash from an unknown blog post or random repository.
Why Short SHAs Are Not Ideal
Git supports abbreviated commit identifiers, but security-sensitive workflow references should be explicit.
For example:
@8ade135
is easier to type, but it is not as clear as:
@8ade135a41bc03ea155e62e844d188df1ea18608
Use the full commit SHA for production workflow references.
Pinning Every Action Is Not the Same as Pinning Dependencies
There are several dependency layers in a CI pipeline.
For example:
GitHub Workflow
|
+-- GitHub Action
|
+-- Action's dependencies
|
+-- Your application dependencies
|
+-- Build tools
Pinning your workflow action to a commit does not automatically pin every dependency used internally by that action.
It gives you a stable reference to the action repository's state at that commit.
This distinction is important when evaluating your supply-chain controls.
Official Actions Should Be Reviewed Too
It is tempting to think that only third-party actions need pinning.
That is not a complete approach.
Official actions can also be pinned:
- uses: actions/checkout@<commit-sha>
- uses: actions/setup-node@<commit-sha>
The reason is not that official actions are inherently untrusted.
The reason is reproducibility.
The same policy can then be applied consistently across the workflow.
Third-Party Actions Need More Scrutiny
Before adding an action to a production workflow, review:
Repository ownership
Maintenance activity
Release history
Permissions requested
Marketplace reputation
Source code
Dependencies
Open issues
Security history
For example:
- uses: third-party/build-action@<commit-sha>
The SHA protects against the reference changing after you pin it.
It does not tell you whether the code at that commit was trustworthy.
Pinning and dependency review solve different problems.
Review Workflow Permissions
Pinning actions is only one part of securing GitHub Actions.
Also review the workflow permissions.
For example:
permissions:
contents: read
This gives the workflow a much smaller default permission scope than an unrestricted configuration.
If a job needs more permissions, grant them deliberately.
For example:
permissions:
contents: read
packages: write
The exact permissions should match what the job actually requires.
A pinned malicious action with excessive permissions is still dangerous.
Avoid One Large Workflow With Broad Permissions
A common pattern is giving an entire workflow broad permissions because one deployment step requires them.
For example:
Build
|
+-- Test
+-- Package
+-- Deploy
The build and test steps may not need deployment permissions.
A better approach is to separate jobs and permissions when practical:
Build Job
|
+-- Read source
+-- Run tests
Deploy Job
|
+-- Read artifact
+-- Deployment permission
This limits the blast radius if one action behaves unexpectedly.
The Maintenance Problem With SHA Pinning
This is where many teams struggle.
Suppose your workflow contains:
- uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608
The action maintainer releases a new version containing a bug fix.
Your workflow does not automatically move to that version.
That is intentional.
But someone now needs to review and update the SHA.
Without a maintenance process, pinned actions become stale.
The solution is not to remove pinning.
The solution is to automate dependency updates.
Use Automated Dependency Updates
Tools such as Dependabot can help identify updates to GitHub Actions.
A Dependabot configuration can include:
version: 2
updates:
- package-ecosystem: github-actions
directory: "/"
schedule:
interval: weekly
This allows action updates to appear as pull requests instead of requiring developers to manually check every workflow.
The exact configuration should match your repository maintenance process.
Review Action Update Pull Requests
An automated pull request should still be reviewed.
Check:
Old SHA
New SHA
Release notes
Security changes
Workflow changes
Required permissions
Test results
The goal is to make action updates routine.
A good process looks like:
New action release
|
v
Automated update PR
|
v
CI tests
|
v
Code review
|
v
Merge
This is much easier to manage than manually searching for action releases.
Do Not Update Action SHAs Blindly
An automated update should not automatically receive production access simply because the commit changed.
Review the update like any other dependency.
For security-sensitive workflows, ask:
What changed?
Why was it changed?
Does it modify permissions?
Does it change shell commands?
Does it add dependencies?
Does it alter artifact handling?
The amount of review should reflect the action's role.
Separate Build and Deployment Actions
A deployment action usually deserves more scrutiny than a formatting action.
For example:
Lint Action
|
+-- Limited access
Test Action
|
+-- Source code access
Deployment Action
|
+-- Cloud credentials
+-- Production access
Do not give every action the same permissions.
Keep sensitive deployment steps isolated where possible.
Be Careful With Secrets
A pinned action does not automatically protect secrets.
Consider this workflow:
steps:
- uses: trusted/action@<commit-sha>
- run: npm test
env:
API_KEY: ${{ secrets.API_KEY }}
The secret is available to the process running that step.
Avoid passing secrets to steps that do not need them.
Prefer the smallest possible scope.
For example, keep deployment credentials inside the deployment job rather than making them available to the complete workflow.
Pin Reusable Workflows Too
Organizations often use reusable workflows:
jobs:
build:
uses: company/reusable-workflows/.github/workflows/build.yml@main
Using a branch such as main means the referenced workflow can change without a change to the calling repository.
For stronger reproducibility, pin reusable workflow references to a specific commit or controlled version.
For example:
jobs:
build:
uses: company/reusable-workflows/.github/workflows/build.yml@<commit-sha>
This is particularly useful when many repositories share the same deployment workflow.
Centralized Workflows Require a Maintenance Strategy
Pinning a reusable workflow creates another maintenance question.
Suppose ten repositories use:
Company reusable workflow
|
+-- Repository A
+-- Repository B
+-- Repository C
+-- ...
If every repository pins a different SHA, updating the shared workflow can become difficult.
A practical organization-wide process should define:
Who maintains the reusable workflow
How releases are announced
How repositories update their SHA
How breaking changes are communicated
How security fixes are prioritized
Centralization helps only when maintenance is also centralized.
Use CODEOWNERS for Sensitive Workflows
GitHub workflow files can affect production systems, so changes should receive appropriate review.
A CODEOWNERS rule can help ensure workflow changes receive review from the responsible team.
For example:
.github/workflows/ @platform-team
This does not replace security controls, but it adds an organizational review boundary.
The exact ownership model depends on the repository.
Review Workflow Changes as Code Changes
A workflow file is executable configuration.
Treat it like application code.
Review changes to:
.github/workflows/
with the same care used for changes to:
src/
infrastructure/
deployment/
Look for:
New actions
Changed SHAs
New permissions
New secrets
Shell commands
External downloads
Artifact changes
Deployment changes
A seemingly small workflow change can have significant consequences.
Avoid Downloading and Executing Unknown Scripts
A workflow such as:
- run: curl https://example.com/install.sh | bash
introduces another supply-chain dependency.
The script can change independently from the workflow.
If external scripts are necessary, prefer downloading a known version and verifying its integrity where practical.
Better still, use maintained actions or controlled build tooling when they provide the required functionality.
Check What an Action Actually Does
Do not choose an action based only on its name.
An action repository may contain:
action.yml
src/
dist/
package.json
README.md
Review the action metadata and source where appropriate.
Pay attention to:
The purpose of pinning is to control what code executes.
You should therefore understand what that code does.
Composite Actions Need Review
Repositories can define their own composite actions.
For example:
runs:
using: composite
steps:
- shell: bash
run: npm ci
- shell: bash
run: npm test
Internal actions are still executable code.
Review them as carefully as external actions.
If a shared composite action changes, all workflows using it may be affected.
A Practical Pinning Strategy
A reasonable approach for many teams is:
1. Inventory all actions
|
v
2. Remove branch references
|
v
3. Pin important actions
|
v
4. Use full commit SHAs
|
v
5. Configure automated updates
|
v
6. Review update PRs
|
v
7. Monitor workflow failures
This avoids treating pinning as a one-time task.
Example of a More Controlled Workflow
A workflow can combine pinned actions with limited permissions:
name: Build
on:
push:
branches:
- main
permissions:
contents: read
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608
- name: Setup Node.js
uses: actions/setup-node@<commit-sha>
with:
node-version: 22
- name: Install dependencies
run: npm ci
- name: Run tests
run: npm test
The important characteristics are:
Actions are pinned
Workflow permissions are explicit
Dependencies are installed through the lockfile
Tests run before deployment
Runtime versions are controlled
Replace placeholder SHAs with the verified commit SHA for the specific action version you intend to use.
Common Mistakes
Pinning to a Branch
Avoid:
uses: actions/checkout@main
A branch is mutable.
Pinning to a Short SHA
Use a full commit SHA for production workflows.
Pinning and Never Updating
A pinned action can still contain an old version.
Track updates through automation.
Giving Every Job Broad Permissions
Permissions should match the job's responsibilities.
Passing Secrets to Every Step
Keep secrets scoped to the steps that actually need them.
Trusting an Action Because It Is Popular
Popularity does not replace code review and dependency management.
Changing the SHA Without Reviewing the Release
Treat action updates as dependency updates.
A Useful Review Checklist
Area | Check |
|---|
Action references | Use controlled versions |
SHA | Use full commit SHA |
Branch references | Avoid mutable branches |
Permissions | Grant minimum required access |
Secrets | Limit secret exposure |
Third-party actions | Review source and ownership |
Reusable workflows | Pin controlled references |
Updates | Automate update detection |
Pull requests | Review action changes |
CODEOWNERS | Protect workflow files |
Testing | Run CI after updates |
Deployment | Isolate privileged jobs |
Advantages
Pinning GitHub Actions provides several useful benefits:
More predictable builds
Better supply-chain control
Easier incident investigation
Reduced unexpected workflow changes
Clearer dependency history
Better auditability
It also makes it easier to answer a simple question during an incident:
"What exact action code did this workflow execute?"
With a mutable tag, that answer can become difficult to establish.
With a commit SHA, the workflow identifies a specific repository state.
Disadvantages
Pinning also introduces maintenance work.
Action updates require review
Security fixes do not automatically enter the workflow
SHAs are harder to read than version tags
Large organizations need an update process
Stale pins can become a security problem
These are manageable problems when automated dependency updates are part of the workflow.
Summary
Pinning GitHub Actions is useful because CI workflows are part of the application's supply chain.
A version tag is convenient, but a full commit SHA gives you a fixed reference to the action code that the workflow executes.
The mistake is treating pinning as a one-time security task.
A pinned action still needs security updates, bug fixes, and maintenance. The practical solution is to combine immutable references with automated dependency update tools, code review, controlled workflow permissions, and limited secret access.
The result is a CI pipeline that is both predictable and maintainable.
The goal is not to freeze GitHub Actions forever. It is to make every change to the code running inside your CI pipeline deliberate, reviewable, and traceable.
GitHub ActionsCI/CD securityaction pinningcommit SHAsoftware supply chainworkflow permissions
Join the conversation! Your thoughts help the community grow.