github-actions-version-pinning

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

1. Identify every uses: reference in changed workflow files.
2. 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.
3. 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.
4. 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.
5. 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.