pinned-tag

Pinned Tag Management Skill

Skill for managing "pinned tags" and commit SHAs, primarily for GitHub Actions security.

Overview

This skill helps locate and validate tags in remote repositories using git ls-remote --tags, resolving the specific commit SHA for a tag (including annotated tags), and providing patches to pin dependencies. It specifically targets GitHub Actions security best practices by encouraging the use of full commit SHAs instead of mutable tags.

When to Use

• You need to fix "Unpinned tag for a non-immutable Action in workflow" security alerts.
• You want to ensure reproducibility by pinning a GitHub Action or dependency to a specific commit SHA.
• You need to verify if a tag exists before updating a manifest or CI workflow.

Critical Patterns

• Immutability for Actions: For GitHub Actions, always prefer the full 40-character commit SHA over a tag name. Tags are mutable and can be moved, leading to security risks or broken builds.
• Annotated vs Lightweight Tags:
  • Annotated Tags: git ls-remote returns two entries. The one ending in ^{} is the " peeled" reference pointing directly to the commit object. ALWAYS use this one.
  • Lightweight Tags: Return only one entry, which is the commit SHA.
  • Selection Logic: When resolving, always sort the results and take the last one to ensure ^{} is preferred over the tag object SHA.
• Verification: Always verify the resolved SHA belongs to the expected tag before applying changes.

Commands

1. Resolve Tag to SHA (GitHub Actions Friendly):

   # Example: Resolve 'v2' tag for actions/checkout
   # This command ensures that for annotated tags, the commit SHA (peeled tag ^{}) is selected
   # by sorting and taking the last entry (where ^{} alphabetically follows the base tag).
   git ls-remote --tags https://github.com/actions/checkout.git | rg "refs/tags/v2(\^\{\})?$" | sort | tail -n 1 | awk '{print $1}'