github-actions-version-check

A CLI tool to check and update GitHub Action versions in workflow files.

It scans .github/workflows, detects outdated uses: references, and can optionally rewrite them in place.

✨ Features

• Detect outdated GitHub Actions (uses: owner/repo@ref)
• Supports semantic version comparison
• Safe updates within the same major version by default
• Optional major upgrades (--allow-major)
• In-place rewriting (--fix)
• Pre-commit integration
• XDG-compliant cache (with TTL) to reduce GitHub API calls
• Works without a token (but supports GITHUB_TOKEN for higher limits)

📦 Installation

Using uv (recommended)

uvx github-actions-version-check

Using pipx

pipx install github-actions-version-check

🚀 Usage

Check workflows

github-actions-version-check

Exit codes:

• 0 → everything is up to date
• 2 → outdated refs found
• 1 → error

Check a specific directory

github-actions-version-check /path/to/repo

Fix outdated versions

github-actions-version-check --fix

Allow major upgrades

github-actions-version-check --fix --allow-major

Show version

github-actions-version-check --version

⚙️ Configuration

Environment variables

🧠 How it works

• Scans .github/workflows/*.yml and .yaml
• Extracts uses: lines
• Resolves latest versions via GitHub API
• Compares semantic versions
• Optionally rewrites outdated refs

Supported patterns

uses: actions/checkout@v4
uses: owner/repo@v1.2.3

Limitations

• Only simple uses: lines are supported
• Multiline YAML (|, >) is not parsed
• SHA-pinned actions are skipped

🔌 Pre-commit integration

repos:
  - repo: https://github.com/<owner>/github-actions-version-check
    rev: vX.Y.Z
    hooks:
      - id: github-actions-version-check
        args: [--fix]

🗂 Cache

Stored in:

$XDG_CACHE_HOME/github_actions_version_check/github-api.json

Fallback:

~/.cache/github_actions_version_check/github-api.json

🛠 Development

uv sync
uv run pytest
uv run mypy

📄 License

MIT