| name | github-actions-version-pinning |
| description | Verify and pin GitHub Actions versions in workflow files. Use when creating, editing, or reviewing `.github/workflows/*` files, changing `uses:` references, adding external actions, responding to CI/security review feedback about action versions, or checking whether actions are pinned to the latest appropriate version. |
GitHub Actions Version Pinning
Overview
Ensure workflow actions use current, intentional pins. Prefer exact patch tags or immutable SHAs for third-party actions when practical; use latest major tags only when the repository convention or user explicitly asks for major-version pins. Treat non-GitHub actions as supply-chain risk unless the user or repository policy has already approved them.
Workflow
- Identify every
uses: reference in changed workflow files.
- Classify each reference:
- Official GitHub action:
actions/*, github/*.
- Third-party action: everything else.
- Local action:
./...; do not version-pin local actions.
- Existing SHA pin: preserve it unless the user explicitly asks to update or replace it.
- Check the official upstream source for the latest release before changing versions.
- Prefer
gh release view --repo OWNER/REPO --json tagName,isLatest when authenticated and available.
- Otherwise fetch
https://github.com/OWNER/REPO/releases/latest or inspect upstream tags.
- Apply pinning policy:
- Respect repository policy first. Some repositories consider official GitHub actions safe with tag pins; others require SHA pins for every external action.
- Default security preference: pin external actions to the latest exact patch tag, for example
actions/checkout@v6.0.2 or jdx/mise-action@v4.0.1.
- If the user or repo policy asks for major-version pins, pin to the latest major tag, for example
actions/checkout@v6.
- If GitHub's API shows a tag version is immutable, treat that tag as equivalent to a SHA. Prefer immutable tag pins over raw SHAs because they stay readable, but add a workflow comment noting that the tag was verified immutable.
- For high-risk or untrusted third-party actions without immutable tags, prefer a full commit SHA and include a comment or documentation of the corresponding release tag when useful.
- Avoid adding new third-party actions without explicit user consent. If an external action would be convenient, ask first and explain the supply-chain risk.
- Validate workflow schemas after edits if a local task exists, for example
task validate:file -- .github/workflows/ci.yml.
Rules
- Do not assume
@vN is latest. Verify upstream first.
- Do not use floating branch refs like
@main or @master for external actions unless explicitly requested.
- Do not downgrade from an exact patch/SHA pin to a major tag unless explicitly requested.
- Do not replace an existing SHA pin with a tag unless GitHub's API verifies the tag is immutable or the user explicitly requests it. If using an immutable tag, add a comment documenting that verification.
- Do not introduce a new third-party action silently. Prefer built-in shell commands or official GitHub actions when possible, and ask before adding third-party actions.
- Mention verified upstream latest versions in the final response when version changes were made.
- If an action has no releases, use a specific tag if available; otherwise consider a commit SHA.
Examples
uses: actions/checkout@v5 with latest release v6.0.2: prefer actions/checkout@v6.0.2; use @v6 only when latest-major pinning is requested.uses: jdx/mise-action@v3 with latest release v4.0.1: prefer jdx/mise-action@v4.0.1; use @v4 only when latest-major pinning is requested.uses: docker/login-action@v3: check latest docker/login-action release; if already on latest exact patch or accepted major pin, leave unchanged.
