Third-party Actions are dependencies. A floating tag behaves like an unpinned package dependency. If the reference changes, the workflow can execute different code without any change to your repository.

This article shows you how to prevent poisoned continuous integration (CI) dependencies by pinning Actions to full commit SHAs, validating those pins against release tags, restricting permitted actions, and automating reviewed updates with Dependabot.

Who this is for: Platform and DevSecOps engineers securing GitHub Actions workflows.

Prerequisites:

• Repository admin access

• Workflows using uses: org/action@ref syntax

The Quick Reference:

Here's what you'll learn how to do here:

• Pin every uses: reference to a full commit SHA, not a moving tag such as @v4.

• Validate that each recorded SHA matches the release you reviewed before approving it.

• Maintain an allowlist of permitted actions at the organization or repository level.

• Enable Dependabot for GitHub Actions version bumps with review.

• Prefer official or verified creators. Mirror critical actions internally if needed.

• Verify pins in pull request checks before merge.

Table of Contents

• The Quick Reference

• Why Floating Tags Fail

• Pin Actions to Commit SHAs

• Validate the Commit SHAs

• Enable Dependabot for Actions

• Allowlist Actions

• Enforce Pins in Pull Requests

• Vet Third-Party Actions

• How to Verify This Works

• When This Breaks Down

• Conclusion

• References

Why Floating Tags Fail

GitHub Actions lets you reference a dependency with a branch name, version tag, or commit SHA. These references don't provide the same level of stability. A branch can change at any time, and a version tag can be moved to a different commit after you review it. A commit SHA identifies one specific revision.

The table below compares the common reference styles and shows why a moving tag creates a supply chain risk:

The first three references fail because the name doesn't permanently identify the code that GitHub will execute. A full SHA solves that specific problem by making the workflow change only when someone changes the reference in the repository.

Key idea: CI pipelines deserve the same dependency discipline as application code.

Pin Actions to Commit SHAs

Pinning an Action means replacing its branch or version tag with the full SHA of the commit you reviewed. GitHub then checks out that exact revision, even if the publisher later moves the original tag.

This first example is bad because both references use mutable version tags. The workflow may run different Action code later without a corresponding change in your repository:

- uses: actions/checkout@v4
- uses: actions/setup-node@v4

This second example is good because each reference uses a full 40-character commit SHA. The comments preserve the readable release versions for maintainers, but GitHub uses the SHA rather than the comments:

- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
- uses: actions/setup-node@4992456781334f2795ae9dd169f5041797d85689 # v4.4.0

Find the SHA on the action's GitHub release page or:

gh api repos/actions/checkout/git/ref/tags/v4.2.2 --jq '.object.sha'

Use the exact release tag you reviewed. Add a comment with the human-readable version for maintainability. The comment helps a reviewer, but it's not part of the security control. GitHub executes the commit identified by the SHA.

Don't use a shortened SHA. A full 40-character SHA makes accidental collisions and ambiguous reviews less likely.

Validate the Commit SHAs

A full SHA protects the workflow from a tag moving after you merge it, but you still need to validate the SHA before approving it. The release tag and commit should be reviewed together. This check compares the commit behind the reviewed tag with the commit recorded in the workflow:

#!/usr/bin/env bash
set -euo pipefail

repository="actions/checkout"
release_tag="v4.2.2"
expected_sha="11bd71901bbe5b1630ceea73d27597364c9af683"

actual_sha="$({
  git ls-remote "https://github.com/${repository}.git" \
    "refs/tags/${release_tag}" "refs/tags/${release_tag}^{}"
} | awk -v tag="refs/tags/${release_tag}" '
  $2 == tag "^{}" { print $1; found = 1 }
  $2 == tag { fallback = $1 }
  END { if (!found) print fallback }
')"

if [[ "${actual_sha}" != "${expected_sha}" ]]; then
  printf 'SHA mismatch for %s %s\n' "${repository}" "${release_tag}" >&2
  printf 'Expected: %s\nActual:   %s\n' "${expected_sha}" "${actual_sha}" >&2
  exit 1
fi

printf 'Validated %s@%s\n' "${repository}" "${expected_sha}"

This is release-reference validation, not a claim that a repository is trustworthy. Read the action source, review its permissions, and record why you approved the dependency. For higher-assurance environments, mirror critical actions internally and validate the mirrored artifact through your normal repository controls.

Enable Dependabot for Actions

Dependabot is GitHub's automated dependency-update service. For GitHub Actions, it checks the workflow references for newer releases and opens pull requests that update them. This gives you a reviewable place to inspect and approve an Action update instead of changing pins manually or using floating tags.

Create .github/dependabot.yml:

version: 2
updates:
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"
    groups:
      actions:
        patterns:
          - "*"

Dependabot opens pull requests when pinned SHAs have newer releases. Review and merge like application dependencies.

Don't configure Dependabot to merge these updates automatically until you have a review process for action changes. An update can contain new permissions, changed scripts, or a new transitive dependency.

For each update pull request, compare the old and new commit, inspect the action's release notes, and review changes to action.yml JavaScript bundles, shell scripts, and workflow permissions. Confirm that the new commit belongs to the release you intended to adopt. Run the workflow in a test repository or environment when the action handles deployment, publishing, credentials, or other high-impact operations.

The goal isn't to reject every update. The goal is to make the trust decision visible and repeatable. A reviewer should be able to answer three questions before merging: what code changed, why is the new version needed, and what permissions can that code use?

Allowlist Actions

An Action allowlist is a repository or organization policy that limits which publishers and repositories workflows are allowed to call. It reduces the chance that a contributor introduces an unknown or unreviewed Action into a trusted pipeline.

Organization administrators can configure it at Settings → Actions → Policies → Allow specified actions. Choose the narrowest policy that matches your workflows, then add only the Action repositories your teams have reviewed.

Example allowlist patterns:

actions/checkout@*
actions/setup-node@*
actions/cache@*
docker/*
my-org/*

With this policy, Actions that don't match the approved patterns are denied. Repositories under the organization inherit the policy, subject to the organization's GitHub plan and repository settings.

For a single repo without an org policy, use Settings → Actions → General → Allow actions created by GitHub, and select non-GitHub actions and restrict to verified creators only.

An allowlist limits which action identities may run. It doesn't replace SHA pinning. A permitted action should still be referenced by a reviewed full SHA in every workflow.

Enforce Pins in Pull Requests

Run a workflow linter in CI and add a repository check that fails when a workflow introduces a non-SHA reference. Pin the checker itself before using it in a protected workflow. Replace the placeholder below with the full commit SHA you verified for the actionlint release you selected:

name: actionlint

on:
  pull_request:

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
      - uses: rhysd/actionlint@03d0035246f3e81f36aed592ffb4bebf33a03106 # v1.7.7
        with:
          args: -color

Resolve the release tag, review the commit, and record the full 40-character SHA just as you did for actions/checkout.

You can also use a small check to catch common floating references. Treat this as a backup signal, not a YAML parser or a complete supply chain policy:

      - name: Reject floating action tags
        run: |
          if grep -RInE '^[[:space:]]*-?[[:space:]]*uses:[[:space:]]*[^#]+@(main|master|v[0-9]+)([[:space:]]|$)' .github/workflows/; then
            echo "Floating action refs found. Pin to full SHA."
            exit 1
          fi

The check should run on pull requests and on protected branches. A pull request can pass this test and still contain a malicious commit, so combine it with code review, the allowlist, and the SHA validation process.

Vet Third-Party Actions

Before adding a community action to the allowlist:

1. Read the action's action.yml and entry script.

2. Check star history, maintainer reputation, and open security issues.

3. Pin SHA and fork to my-org/action-name if the action is critical but externally maintained.

Also inspect the permissions available to the workflow. An action that can read repository secrets or write releases deserves more scrutiny than an action that only formats a file. Set the workflow's top-level permissions to the minimum required, then grant additional permissions to individual jobs only when needed.

How to Verify This Works

1. Run the SHA validation script for every action you approve and expect all comparisons to pass.

2. Open a test pull request that changes an action to@main, and confirm the CI gate fails.

3. Add a trailing comment after a floating tag and confirm your parser or linter still rejects it.

4. Confirm organization policy blocks a disallowed action in a test workflow.

5. Confirm Dependabot opens an action update pull request and that the change receives normal review.

6. Review the workflow run permissions and verify that the action can't access credentials it doesn't need.

When This Breaks Down

1. Emergency patches: SHA pinning slows hotfixes. Dependabot plus on-call review is safer than temporarily using a floating tag.

2. Composite actions in private repos: pin internal actions the same way as public ones.

3. Reusable workflows: pin the reusable workflow ref to SHA as well as steps inside it.

4. Annotated tags and mirrors: resolve annotated tags to their commit before recording a SHA, and validate internal mirrors through your own change-control process.

5. False sense of safety: pinning without reading code still trusts the maintainer at pin time. Combine pinning with allowlists, least-privilege permissions, and review.

Conclusion

In this tutorial, you learned how to prevent poisoned CI dependencies by pinning GitHub Actions to reviewed commit SHAs, validating those references, allowlisting trusted actions, enabling Dependabot updates, and enforcing pins in pull request checks.

The result is a layered control: a reviewed immutable reference, a restricted set of permitted actions, automated update proposals, and a pull request check that catches regressions before merge.

References

• GitHub Actions, Security hardening

• GitHub, Dependabot version updates for Actions

• StepSecurity, Pin GitHub Actions

• OpenSSF, Source compromise defenses

The problem is easy to miss because the workflow still passes, so the extra access often goes unnoticed until a review, incident, or failed release exposes it.

This matters because GitHub Actions sits in the middle of code, secrets, releases, and deployment automation. If you tighten permission scope at the workflow and job level, you reduce what an attacker can do if a step, action, or dependency is compromised.

In this tutorial, you'll learn how to identify the permissions a workflow actually needs, reduce those permissions to the minimum practical scope, and verify that the workflow still works when access is intentionally constrained.

Start with one existing workflow, make its permission model explicit, and then remove access that the workflow never uses.

What We'll Cover:

• Prerequisites

• Key Points

• What You'll Build

• Why the Default Approach Fails

• How to Implement This Safely

• How to Verify This Works

• When This Breaks Down

• Conclusion

• References

Prerequisites

You should already have a GitHub repository with at least one workflow file and permission to edit repository settings and workflow YAML.

You'll also need a basic understanding of GitHub Actions jobs, permissions, and pull request workflows.

Key Points

• Start with the smallest workflow permission set that still lets the job run.

• Give write access only to the job that needs it.

• Use OIDC for cloud access instead of long-lived credentials when the workflow reaches AWS or another provider.

• Verify that the workflow still succeeds after you remove excess permissions.

What You'll Build

You'll take one existing GitHub Actions workflow and turn it into a tighter version that gives each job only the access it needs.

That usually means a read-only test job, a separate release job with write access, and cloud deployment jobs that use short-lived OIDC credentials instead of stored secrets.

Why the Default Approach Fails

A common pattern is to let a workflow inherit broad repository token access and only think about security after the pipeline is already working. That feels convenient, but it makes every job look more trusted than it really is.

The safer approach is to treat each job as a separate boundary. A build job usually needs read access, while a release job may need a narrow write scope. The goal is not to make every workflow restrictive for its own sake, but to make each permission explicit and easy to review.

For example, a test workflow should usually read code and upload artifacts. It shouldn't automatically be able to push tags, publish releases, or write to package registries.

How to Implement This Safely

Step 1: Inventory What the Workflow Actually Does

Before you edit YAML, list the actions the workflow performs. For example, a test job may only need to clone code and upload test artifacts, while a release job may need to create a release or push a package.

That split matters because GitHub Actions permissions can be different at the workflow level and the job level.

If you're not sure where to start, inspect the workflow and ask one question: does this job need to read, write, or do both?

Here's a simple permission audit you can apply to most workflows:

Use the table as a starting point, then reduce access further if your workflow is even simpler.

Step 2: Set a Minimal Default Permission Scope

Start with the workflow permission block and grant only what the majority of jobs need.

If the job only checks code or runs tests, contents: read is usually enough.

name: ci

on:
  pull_request:
  push:
    branches:
      - main

permissions:
  contents: read

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm test

With this baseline, the workflow can read repository content, but it doesn't get extra write access by default.

Step 3: Add Write Access Only Where the Job Needs it

If one job creates a release or publishes a package, give that job a narrower permission set instead of widening the whole workflow.

Keep the write scope on the smallest job that needs it. That keeps the rest of the pipeline easier to audit.

  release:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    needs: test
    steps:
      - uses: actions/checkout@v4
      - run: ./scripts/release.sh

This keeps your build path narrow while still allowing the one job that genuinely needs write access to complete its work.

Step 4: Use OIDC for Cloud Access When the Workflow Leaves GitHub

If the workflow needs cloud access, configure OIDC instead of storing long-lived credentials in secrets. That way, the job requests a temporary token at runtime, and you avoid keeping static cloud keys in the repository.

permissions:
  contents: read
  id-token: write

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Configure cloud credentials
        run: echo "Configure OIDC-based credentials here"

Step 5: Verify That Unnecessary Access is Gone

Run the workflow after removing excess permissions and confirm two things.

First, the intended job still succeeds. Second, a step that tries to use a permission you removed should fail clearly.

A good review signal is that the workflow logs show the exact permission scope you set, and any blocked write attempt fails instead of silently succeeding.

If the workflow only works when you widen permissions again, split the job or move the write action into a smaller release workflow.

You can also prove the change by trying one deliberate failure case. For example, run a release step in a branch where the job only has contents: read. The step should fail instead of silently publishing a release.

How to Verify This Works

Use a small test branch and push a commit that triggers the workflow.

Then confirm that:

• The read-only job still passes.

• The release job only works when it has explicit write permission.

• A blocked action fails fast instead of receiving a token with broader access.

If you use a security scanner or linting step, keep it in the workflow so the permission change doesn't break normal delivery.

Check the workflow run summary, not just the final status. The logs should show that the job requested only the permissions it actually needs, and the denied action should fail because the token can't write.

That gives you a clear audit trail and a simpler review path for every future change to the workflow.

The strongest signal is a workflow that still passes with the smallest reasonable permission set and fails only when you intentionally remove a needed permission.

If you want an extra confidence check, compare the YAML before and after the change. The new version should show a narrow default at the workflow level and only a small number of job-level exceptions.

When This Breaks Down

This approach isn't magic. Some repositories have workflows that do many different things, and those workflows may need to be split before permission scoping becomes clean.

It can also feel slower at first because every permission change becomes explicit. That is the trade-off: a little more setup now in exchange for a much clearer security boundary later.

Finally, least privilege doesn't replace code review or secret scanning. It only reduces what a compromised workflow can do.

It also has limits when third-party actions need wider access than you expected. In that case, the next step is to review the action itself, not just the workflow that calls it.

Conclusion

In this tutorial, you learned how to narrow GitHub Actions permissions to the minimum needed, split read and write responsibilities across jobs, and verify that the workflow still works after the access model is tightened.

As a next step, you can apply the same pattern to release pipelines, package publishing, or cloud deployment workflows that still rely on broader permissions than they should.

References

• Automatic token authentication for GitHub Actions

• Workflow syntax for GitHub Actions, permissions

• Security hardening with OpenID Connect