gx

Package manager for Github Actions. Like go mod tidy for your workflows.

Why gx?

• Security: Github recommends pinning actions to commit SHAs to prevent supply chain attacks. Maintaining SHAs by hand is tedious and error-prone.
• Automation: gx resolves version tags to commit SHAs, updates your workflows, and keeps everything in sync.
• Flexibility: Run with zero configuration (memory-only mode) or create a manifest for team reproducibility.
• Upgrades: Check for newer versions and upgrade with a single command, respecting your version precision.

Quick start

# Pin all actions in your workflows to commit SHAs

gx tidy


# Or initialize a manifest for reproducible builds

gx init

Before:

- uses: actions/checkout@v4

After:

- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4

Installation

From crates.io

cargo install gx

From source

git clone https://github.com/gmeligio/gx.git

cd gx

cargo install --path .

Commands

tidy

The command you'll run most often. It doesn't require configuration.

Update pinned SHAs when action versions change in your workflows. If gx.toml exists, ensure it matches the workflows — add missing actions, remove unused ones, and update the lock file.

gx tidy

Learn more

init

Set up gx with a manifest and lock file for team reproducibility. Creates gx.toml and gx.lock from your current workflows.

gx init

Learn more

upgrade

Check for newer versions of actions and upgrade them. Resolves new SHAs and updates workflows. Skips non-semver versions.

gx upgrade

Learn more

How it works

gx operates in two modes:

• Memory-only (no gx.toml): Scans workflows, resolves SHAs, and updates workflow files in place. No manifest or lock files are created.
• File-backed (with gx.toml): Maintains a manifest (.github/gx.toml) and lock file (.github/gx.lock) for reproducible builds across your team.

gx uses a two-phase approach to extract version information from workflows. Since YAML parsers strip comments, it first scans raw content for version comments (uses: action@SHA # v4), then parses the YAML structure and merges the results.

Configuration

• Manifest file (.github/gx.toml) — defines which versions to use, with support for hierarchical overrides
• Lock file (.github/gx.lock) — stores resolved commit SHAs for reproducible builds

Options

• -v, --verbose — Enable verbose output
• --version — Print version

Environment

• GITHUB_TOKEN — Optional, needed for resolving commit SHAs via the Github API. Create a token.

Documentation

Contributing

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

License

MIT