gx

Package manager for GitHub Actions.

gx tidy demo

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

Already using another tool?

gx works alongside your existing setup.

If you use…	gx adds…
No tool	SHA pinning, version upgrades, lint, and a manifest to keep your team in sync
Renovate	A local CLI (no bot/PR required), lint checks, and a manifest/lock system for auditing
Dependabot	Initial SHA pinning (not yet supported by Dependabot), lint, and a manifest/lock system
ratchet	A manifest/lock system for team reproducibility, and standard version comments (no `# ratchet:` prefix)
pinact	A manifest/lock system for team reproducibility

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

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.

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

- name: Check action pins
  run: gx lint

Contributing

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

License

MIT

gx 0.8.3

gx