---
name: update-github-actions-versions
description: >-
  Audits GitHub Actions workflow files for outdated `uses:` references, resolves
  current major (or latest) tags from each action’s repository, and updates
  YAML to match—fixing stale pins like actions/checkout@v4 when v6 is current.
  Use when refreshing workflows, after copying samples from docs, or when the
  user asks to bump GitHub Actions versions.
---

# Update GitHub Actions `uses:` versions

## Scope

- **In scope:** workflow files under **`.github/workflows/`** (and composite definitions under **`.github/actions/`** only when scanning for embedded external `uses:`—skip **`uses: ./...`**).
- **Out of scope:** **`docker://...`** images (different versioning), **`runs:`** runner labels, **`actions/github-script`** inline scripts.

## Workflow for the agent

1. **Collect** every **`uses:`** string from `*.yml` / `*.yaml` in **`.github/workflows/`** (include reusable workflows if present).
2. **Normalize** each reference:
   - **`owner/repo@ref`** → note `owner`, `repo`, current `ref` (e.g. `v4`, `v4.2.0`, a SHA).
   - Skip **`./...`** and **`docker://...`**.
3. **Resolve latest** for **`owner/repo`** (see [reference.md](reference.md)): prefer the **current major floating tag** GitHub documents for first-party actions (e.g. **`v6`** for `actions/checkout` when that is the latest major), not necessarily every patch SHA unless the user asks for SHA pinning.
4. **Compare**: if the workflow uses an **older major** (e.g. `v4` vs latest `v6`) or a **stale minor** on the same major when the team wants strict freshness, plan an update.
5. **Read release notes** for **major** jumps (`v4` → `v6`): summarize breaking changes in the PR/summary to the user.
6. **Edit** workflows: replace only the **`@ref`** segment; keep indentation and **`id:`** / **`with:`** blocks unchanged.
7. **Sanity check**: ensure composite inputs still match the new action version (rename `inputs` in upstream release notes).

## Rules

- **Do not invent** versions: resolve from **GitHub (tags/releases)** or **`gh` CLI** at update time—LLM training cutoffs are wrong for “latest”.
- **Prefer Linux-friendly verification** when suggesting a follow-up: `actionlint` or **`gh workflow view`** if available; at minimum re-read edited YAML for valid nesting.
- **Third-party actions** (`trufflesecurity/trufflehog`, etc.) use the same **`repos/{owner}/{repo}/tags`** or **releases** lookup; treat **major** bumps as higher risk.

## Why this exists

Samples and models often default to **older majors** (`actions/checkout@v4`, `actions/upload-artifact@v3`) while maintainers have shipped **new majors** with different inputs, Node runtime, or artifact APIs. This skill forces a **live version check** before editing.

## Commands and APIs

See [reference.md](reference.md) for **`gh`**, **REST**, and **tag-selection** patterns.