actupdate

actupdate updates GitHub Action references in workflow YAML files to the latest eligible stable version.

What It Does

Run actupdate inside a git repo and it will:

1. Scan .github/workflows/*.yml and .github/workflows/*.yaml
2. Optionally scan nested action.yml and action.yaml files when --include-composite-actions is set
3. Find remote uses: references such as actions/checkout@v4
4. Query GitHub for the action repository's tags
5. Prefer moving tags such as v6 or v6.2 when the action publishes them
6. Fall back to the latest verified stable exact tag such as v6.2.1 when the repo does not publish an eligible moving tag
7. Show the planned updates with colorized terminal output when supported
8. Prompt once before rewriting files; pressing Enter accepts the default and applies the changes

Use --pin to select exact releases and write immutable commit pins with version comments. Existing SHA pins with a leading semver comment are upgraded automatically and remain pinned, even without --pin.

The tool skips local actions, Docker references, SHA pins without a leading semver comment, branch refs, and other non-semver references.

Installation

Download a prebuilt binary from the GitHub releases, or install the latest release with Go:

go install github.com/qartik/actupdate/cmd/actupdate@latest

Usage

actupdate

Options:

actupdate --repo /path/to/repo
actupdate --yes
actupdate --pin
actupdate --include-composite-actions
actupdate --cooldown-days 7
actupdate --github-token "$GITHUB_TOKEN"
actupdate --github-tls12
actupdate version

Flags:

• --repo: operate on a different repo root instead of the current directory
• --yes: apply immediately after printing the plan
• --pin: convert tag references to full commit SHAs of eligible exact releases, including references already on the latest release
• --include-composite-actions: also scan nested action.yml and action.yaml files outside .github/workflows
• --cooldown-days: ignore candidate tags newer than the given number of days
• --github-token: override token lookup; otherwise the tool uses GITHUB_TOKEN, then GH_TOKEN
• --github-tls12: cap GitHub API connections at TLS 1.2 as an explicit compatibility workaround

Use --cooldown-days when you want to avoid immediately adopting freshly published action tags. For example, actupdate --cooldown-days 7 only upgrades to tags that are at least seven days old.

Immutable Commit Pins

Run actupdate --pin to upgrade and pin action references, for example:

uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

Pinned updates select the highest stable exact version tag (vX.Y.Z or X.Y.Z), ignoring moving major/minor tags and prereleases. With --cooldown-days, the tool checks exact releases in descending version order and falls back to an older eligible release without downgrading the input version. Repositories without stable exact tags are skipped.

SHA pins with comments beginning with a stable semver token, such as # v1.1.0 explanation, are upgraded automatically. The version comment is an update hint; the tool does not match bare SHA pins to historical tags. Moving version comments such as # v1 migrate to eligible exact releases. Pins with exact version comments only advance to newer versions; repointing the same tag does not refresh an existing pin. Other comment text and YAML formatting are preserved.

Pins always use full 40-character commit SHAs. GitHub Actions does not support abbreviated SHAs in uses: references.

GitHub Auth

If you see verification failed: ... GitHub API rate limited or forbidden, actupdate is usually running without a GitHub token or has exhausted the token's rate limit.

If you already use gh, you can pass its token directly:

GITHUB_TOKEN="$(gh auth token)" actupdate

If GitHub API requests are reset only on a network with a TLS-inspecting firewall or middlebox, --github-tls12 can work around an incompatibility with TLS 1.3 handshakes. This is opt-in because it lowers the maximum protocol version for GitHub API connections; certificate validation, proxy settings, authentication, and other default HTTP behavior remain enabled. Prefer the default, highest supported TLS version on networks where it works.

Releases

Create and publish a GitHub release with a tag like v0.2.0 from https://github.com/qartik/actupdate/releases/new. The release workflow builds the binaries from that tag, injects the tag version into actupdate version, and uploads tarballs for:

• linux/amd64
• linux/arm64
• darwin/arm64

Each release asset is named like actupdate_linux_amd64.tar.gz and contains the actupdate binary.

If a release build needs to be rerun, dispatch the release workflow manually and provide the existing release tag.

Source builds report Go build metadata, such as a tagged version, pseudo-version, or devel-<commit> fallback when no release version is injected.

Verification Rules

• Only stable semver tags are considered
• Pre-release tags such as -rc, -beta, and -alpha are ignored
• Updates move to the latest eligible stable version
• --cooldown-days can exclude newer tags until they have aged past the configured threshold
• For normal tag updates, moving major tags such as v6 are preferred first; moving minor tags such as v6.2 are preferred next; exact tags such as v6.2.1 are the fallback
• Moving refs keep their precision within the same major, so v3 is not rewritten to v3.4 and v3.4 is not rewritten to v3.4.1
• Exact refs can upgrade within the same major, but representation-only changes such as v3.0 to v3.0.0 are ignored
• If any candidate update cannot be verified, the tool prints the failures and does not rewrite any files

Development

Run tests with:

go test ./...