GitHub Actions Version Updater

Scans workflow YAML for uses: pins, asks GitHub for a newer release tag, release commit, or default-branch SHA, and rewrites only the version token. Quotes, comments, and line endings stay as they are. Run it as a scheduled Action that opens a pull request, or as the update-gha CLI on your machine.

The Marketplace listing and GitHub repo are github-actions-version-updater. The PyPI project is update-gha. Same updater, two ways to run it.

Contents

• GitHub Action
  • What it does
  • How the action works
  • Quick start
  • Version sources
  • Release types
  • Action inputs
  • Action outputs
  • Access token
  • Example workflows
  • Git LFS
  • Alternative
• Python package
  • Install
  • How the CLI works
  • Command examples
  • Configuration
  • CLI options
• Development
  • Prerequisites
  • Setup
  • Layout
  • Tests
  • Lint and types
  • Pre-commit
  • Run locally
  • CI
• License

GitHub Action

Add a workflow to this repository. On a schedule (or when you run it by hand) the action scans uses: pins and opens a pull request with the updates.

Get it on the Marketplace

Under the hood it is a composite action: it installs update-gha[action] from this checkout into an isolated CPython 3.14 environment and runs update-gha --pull-request. It does not change the job's python on PATH.

v1 is not a Docker image. Self-hosted runners need bash and outbound network so uv can install that isolated interpreter; Docker is not required.

What it does

Like Dependabot, but only for GitHub Actions:

• Finds uses: pins in .github/workflows and any extra paths you pass
• Looks up a newer release tag, release commit, or default-branch SHA
• Rewrites only the version token — quotes, comments, and line endings stay as they are
• Commits the result and opens a pull request (unless you set skip_pull_request)

Local actions (./path) and container actions (docker://…) are not updated.

How the action works

1. Check out the repository with a token that can write workflow files.
2. Scan workflow YAML for owner/repo@version pins.
3. Ask the GitHub API for a newer version, unless the pin is listed in ignore.
4. Rewrite matching pins in place.
5. Create a branch, push, and open a PR — unless skip_pull_request is true.

Draft, prerelease, and unpublished GitHub releases are ignored.

Quick start

Trigger on a schedule or workflow_dispatch. Save this as .github/workflows/updater.yaml:

name: GitHub Actions Version Updater

on:
  workflow_dispatch:
  schedule:
    - cron: "0 0 * * 0"   # every Sunday

jobs:
  update:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          token: ${{ secrets.WORKFLOW_SECRET }}

      - name: Run GitHub Actions Version Updater
        uses: saadmk11/github-actions-version-updater@v1.0.0
        with:
          token: ${{ secrets.WORKFLOW_SECRET }}

Version sources

update_version_with chooses what is written back into each uses: pin:

Release types

release_types limits which SemVer bumps are applied. It only applies to release-tag and release-commit-sha.

You can combine them: minor, patch.

Two cases leave a pin unchanged instead of guessing:

• The current pin is not SemVer, and release_types is not all
• update_version_with is release-commit-sha, release_types is restricted, and the current SHA cannot be matched to a release tag

Action inputs

Reviewers and labels are applied only when this run opens a new pull request. They are skipped if a PR for that branch already exists.

Action outputs

Set only when this run created a pull request. Empty if you skipped the PR, nothing changed, or a PR for the branch already existed.

- name: Run GitHub Actions Version Updater
  id: update
  uses: saadmk11/github-actions-version-updater@v1.0.0
  with:
    token: ${{ secrets.WORKFLOW_SECRET }}

- name: Use the pull request number
  if: steps.update.outputs.GHA_UPDATE_PR_NUMBER
  run: echo "Opened PR #${{ steps.update.outputs.GHA_UPDATE_PR_NUMBER }}"

Access token

GitHub's default ${{ secrets.GITHUB_TOKEN }} cannot push changes to workflow files. Create a personal access token, add it to the repository Actions secrets, and pass that secret as token.

Classic PAT

• repo — push the branch and open the pull request
• workflow — update workflow files

Fine-grained PAT

• Contents: Read and write
• Workflows: Read and write
• Pull requests: Read and write
• Metadata: Read-only (granted with the permissions above)

Use the same secret on actions/checkout and on this action so the push uses that credential.

Example workflows

All inputs

name: GitHub Actions Version Updater

on:
  workflow_dispatch:
  schedule:
    - cron: "0 0 * * 0"

jobs:
  update:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          token: ${{ secrets.WORKFLOW_SECRET }}

      - name: Run GitHub Actions Version Updater
        uses: saadmk11/github-actions-version-updater@v1.0.0
        with:
          token: ${{ secrets.WORKFLOW_SECRET }}
          committer_username: "actions-bot"
          committer_email: "actions-bot@users.noreply.github.com"
          commit_message: "chore: bump GitHub Actions"
          pull_request_title: "chore: bump GitHub Actions"
          pull_request_branch: "actions-update"
          ignore: "actions/checkout@v4, actions/cache@v4"
          update_version_with: "release-tag"
          release_types: "minor, patch"
          pull_request_user_reviewers: "octocat, hubot"
          pull_request_team_reviewers: "justice-league"
          pull_request_labels: "dependencies, automated"
          extra_workflow_locations: "deploy/workflows, path/to/workflow.yaml"

Write updates without a pull request

Writes the files, prints a diff, and fails the job if anything changed. Use this when another step or a person should commit.

- name: Run GitHub Actions Version Updater
  uses: saadmk11/github-actions-version-updater@v1.0.0
  with:
    token: ${{ secrets.WORKFLOW_SECRET }}
    skip_pull_request: "true"

Git LFS

If the repository uses Git LFS, check out with lfs: false or remove the LFS hooks before this action runs. Otherwise creating the update branch can fail when the LFS binary is not on the runner.

- uses: actions/checkout@v4
  with:
    token: ${{ secrets.WORKFLOW_SECRET }}
    lfs: false

- name: Remove LFS hooks
  run: |
    rm -f .git/hooks/post-checkout .git/hooks/pre-push

- name: Run GitHub Actions Version Updater
  uses: saadmk11/github-actions-version-updater@v1.0.0
  with:
    token: ${{ secrets.WORKFLOW_SECRET }}

Alternative

Dependabot can also bump GitHub Actions. Prefer this action when you want SHA pins, default-branch tips, ignore lists that match exact uses values, or one scheduled PR with your own title, reviewers, and labels.

Python package

update-gha is the CLI the Action runs. Use it locally or in another CI system.

PyPI · Changelog · Issues

• Scans .github/workflows plus extra files or directories
• Rewrites only the version token (YAML structure, quotes, comments, and line endings stay)
• Three version sources: release tag, release commit SHA, default-branch SHA
• SemVer filters (major / minor / patch)
• --check, --dry-run, --diff, --fail-on-update, and JSON output
• Optional --pull-request (install update-gha[action])
• Config from CLI flags, GHA_UPDATE_* environment variables, or [tool.update-gha] in pyproject.toml

Install

Requires Python 3.12 or newer.

# one-off
uvx update-gha --help
pip install update-gha

# in a project
uv add update-gha
uv run update-gha --check

# user-wide tool
uv tool install update-gha

Pull-request mode needs GitPython. Install the extra only if you will pass --pull-request:

pip install 'update-gha[action]'
uv add 'update-gha[action]'
uv tool install --with 'update-gha[action]' update-gha

How the CLI works

1. Scan .github/workflows (and any extra paths) for uses: pins.
2. Ask GitHub for a newer release or commit, unless the pin is ignored.
3. Rewrite only the version token.
4. If you passed --pull-request and files were written, commit, push, and open a PR.

Command examples

update-gha                          # rewrite workflow files in place
update-gha --check                  # do not write; exit 1 if any pin would change
update-gha --dry-run --diff         # do not write; print the plan and a unified diff
update-gha --fail-on-update         # write, then exit 1 if anything was written
update-gha --format json
update-gha --ignore 'actions/checkout@v4'
update-gha --update-version-with release-tag --release-types 'minor,patch'
update-gha path/to/extra.yaml

Open a pull request (needs update-gha[action]):

export GITHUB_TOKEN=...
export GITHUB_REPOSITORY=owner/repo
update-gha --pull-request

--token and --repository work instead of those environment variables. Tracked files must be clean so the commit contains only updater changes; untracked files are left alone.

Configuration

Read in this order (later sources lose to earlier ones):

1. CLI flags
2. Environment variables (GHA_UPDATE_*, plus GITHUB_TOKEN / GITHUB_REPOSITORY)
3. [tool.update-gha] in the nearest pyproject.toml (walks up from the current directory)
4. Built-in defaults

export GITHUB_TOKEN=...
export GHA_UPDATE_IGNORE_ACTIONS='actions/checkout@v4'
export GHA_UPDATE_UPDATE_VERSION_WITH=release-tag
export GHA_UPDATE_RELEASE_TYPES='minor,patch'
update-gha

[tool.update-gha]
ignore_actions = ["actions/checkout@v4"]
update_version_with = "release-tag"
release_types = ["minor", "patch"]
extra_workflow_locations = ["deploy/workflows"]
committer_username = "bot"
pull_request_title = "Update GitHub Action versions"

You can also enable pull-request mode with GHA_UPDATE_CREATE_PULL_REQUEST=true. Commit and PR fields (committer_*, pull_request_*, reviewers, labels) are ignored unless that flag or environment variable is on.

CLI options

See update-gha --help for the full text.

Development

The package lives in src/update_gha. Tests are in tests/. Tooling is configured in pyproject.toml and run with uv (0.11.32 or newer).

Prerequisites

• Python 3.12+ (CI covers 3.12, 3.13, and 3.14; .python-version is 3.14)
• uv 0.11.32 or newer

Setup

git clone https://github.com/saadmk11/github-actions-version-updater.git
cd github-actions-version-updater
uv sync --all-groups --all-extras

That installs the package (editable), the [action] extra (GitPython), and the dev group (pytest, ruff, mypy).

Layout

Tests

uv run pytest

Coverage is required at 100% (--cov-fail-under=100). Tests do not hit the live GitHub API; HTTP and git are faked.

uv run pytest tests/test_rewrite.py          # one file
uv run pytest tests/test_cli.py::test_help   # one test

tests/smoke_test.py is also run by the release workflow against the built wheel and sdist.

Lint and types

uv run ruff check .
uv run ruff format --check .
uv run mypy

Ruff uses a line length of 88. mypy runs in strict mode on src and tests.

To apply fixes:

uv run ruff check --fix .
uv run ruff format .

Pre-commit

.pre-commit-config.yaml runs end-of-file / whitespace checks, Ruff, and mypy. The Ruff and mypy hooks install their own tools, so they work locally and on pre-commit.ci. Install pre-commit separately (it is not in the dev group):

uv tool install pre-commit
pre-commit install
pre-commit run --all-files

Run locally

uv run update-gha --help
uv run update-gha --dry-run --diff
uv run python -m update_gha --check

CI

.github/workflows/ci.yaml runs on pushes and pull requests to main:

• lint — ruff check, ruff format --check, mypy on Python 3.14
• test — pytest on Python 3.12, 3.13, and 3.14

Python dependencies are updated by Dependabot (uv). Action pins in this repository are updated by .github/workflows/update-actions.yaml.

License

Released under the MIT License.