gx

Package manager for GitHub Actions.

Before:

- uses: actions/checkout@v4
- uses: actions/setup-node@v4

After running gx tidy:

- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
- uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4

The tag v4 can point to different code tomorrow. The commit SHA cannot. gx rewrites your workflows to use SHAs and keeps a comment with the version for readability.

Why pin to commits?

When your workflow says actions/checkout@v4, that tag can be moved to point to different code at any time. Pinning to a commit SHA guarantees you always run the exact code you reviewed. GitHub recommends this practice, but doing it by hand is tedious. gx automates it.

Installation

brew install gmeligio/tap/gx

Binary download

Download a pre-built binary for your platform from GitHub Releases.

Cargo

cargo install gx

Commands

gx tidy         # Pin actions to commit SHAs and sync manifest if present
gx upgrade      # Upgrade pinned actions to newer versions (--json for CI/PR automation)
gx lint         # Check action pinning, security, workflow validity, and run: shell scripts (see docs/lint-rules.md)
gx init         # Create a manifest and lock file from your current workflows
gx audit        # Check locked actions for vulnerabilities, mutable refs, and archived repos (requires GITHUB_TOKEN)

All of these cover your workflows and any composite actions in .github/actions.

gx lint checks your workflows offline — safe for a pre-commit hook. gx audit reads .github/gx.lock and checks mutable refs, security advisories (through GitHub's GraphQL API), and archived action repositories (through its REST API). Archival warnings recommend migrating to a maintained alternative: security fixes cannot be published while a repository remains archived. A failed repository metadata lookup produces an error finding without discarding findings for other actions.

Audit reports affected versions as known-vulnerability errors and ignores withdrawn advisories. Repository-wide advisories cover nested actions; advisories naming a specific GitHub action URL cover that subpath only. Unparseable versions and ranges, and prereleases not explicitly matched by a range, produce warnings rather than silently passing. Partial versions are zero-padded: a matching padded version produces a conservative error (for example, v2 against < 2.5.0), even if the actual version may be newer. If the padded version does not match but its version line could overlap the range, audit warns. Errors exit nonzero; warnings alone do not. gx audit --json emits one report without creating a local log file; a failed advisory lookup emits no report.

Already using another tool?

gx works alongside your existing setup.

Running Renovate too? It catches majors; in-range advancement is gx upgrade's job. See docs/renovate.md for how the two fit together.

Configuration

gx works with no configuration. Run gx tidy and your workflows are pinned.

For teams that want reproducibility, gx init creates a manifest (.github/gx.toml) and lock file (.github/gx.lock) that track every pinned action. See the documentation for details on the manifest format and overrides.

FAQ

For gx tidy, gx upgrade, and gx init: no, but without one you're limited to 60 GitHub API requests per hour. For most projects that's enough. Set GITHUB_TOKEN for CI or large repos.

For gx audit: yes, always. It requires authenticated GitHub API access for advisory and repository metadata lookups. Without a token it exits non-zero before loading repository configuration rather than reporting a clean audit it never performed. gx lint never needs one — it makes no network requests at all.

Add gx lint to your workflow to enforce pinning on every PR:

- name: Check action pins
  run: gx lint

To keep actions current, copy docs/gx-upgrade.yml into .github/workflows/. It runs gx upgrade on a schedule and opens a PR with the changes. See docs/upgrade-workflow.md.

gx audit also belongs on a schedule: vulnerabilities can be disclosed and a dependency's repository can become archived without any change to your code. A nightly run catches those security and maintenance risks since your last commit.

- name: Audit locked actions
  run: gx audit
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Contributing

See docs/CONTRIBUTING.md for setup instructions and guidelines. Questions?

License

MIT