setup-gh-cli

A GitHub Action to install the GitHub CLI (gh) on any runner platform with configurable version selection.

📚 Documentation: See docs/ for comprehensive documentation and examples/ for real-world workflow examples.

Features

• 🚀 Install any version of the GitHub CLI
• 🔄 Automatically resolves the latest version
• 🖥️ Cross-platform support (Linux, macOS, Windows)
• 🏗️ Works with amd64, arm64, and 386 architectures
• ⚡ Fast installation with caching support
• 🔒 Secure download from official GitHub releases

Usage

Basic Usage

Install the latest version of the GitHub CLI:

steps:
  - uses: actions/checkout@v4

  - name: Setup GitHub CLI
    uses: GitGoneWild/setup-gh-cli@v1

  - name: Use gh CLI
    run: gh --version

Specific Version

Install a specific version:

steps:
  - uses: actions/checkout@v4

  - name: Setup GitHub CLI
    uses: GitGoneWild/setup-gh-cli@v1
    with:
      version: '2.40.0'

  - name: Use gh CLI
    run: gh --version

With Token (Recommended)

Provide a token to avoid rate limiting when resolving the latest version:

steps:
  - uses: actions/checkout@v4

  - name: Setup GitHub CLI
    uses: GitGoneWild/setup-gh-cli@v1
    with:
      version: 'latest'
      token: ${{ secrets.GITHUB_TOKEN }}

  - name: Use gh CLI
    run: gh --version

Using Outputs

Access the installed version and binary path:

steps:
  - uses: actions/checkout@v4

  - name: Setup GitHub CLI
    id: setup-gh
    uses: GitGoneWild/setup-gh-cli@v1

  - name: Show installed version
    run: |
      echo "Installed version: ${{ steps.setup-gh.outputs.installed-version }}"
      echo "Binary path: ${{ steps.setup-gh.outputs.gh-path }}"

Inputs

Name	Description	Required	Default
version	Version of the GitHub CLI to install	No	latest
token	GitHub token for API requests (helps rate limiting)	No	${{ github.token }}

Outputs

Name	Description
installed-version	The version of the GitHub CLI that was installed
gh-path	The full path to the installed gh binary

Supported Platforms

OS	Architectures
Linux	amd64, arm64, 386
macOS	amd64, arm64
Windows	amd64, 386

Development

Prerequisites

• Python 3.9+
• pip

Setup

# Clone the repository
git clone https://github.com/GitGoneWild/setup-gh-cli.git
cd setup-gh-cli

# Install dependencies
pip install -r requirements.txt
pip install -r requirements-dev.txt

# Run tests
pytest

# Run linting
ruff check src tests
mypy src

Running Locally

# Set the version input (optional, defaults to 'latest')
export INPUT_VERSION="latest"

# Run the action
python -m src.setup_gh_cli.main

License

This project is licensed under the MIT License - see the LICENSE file for details.

Documentation

• Usage Guide - Getting started and usage patterns
• Configuration Reference - All inputs, outputs, and supported platforms
• CI/CD Integration - Patterns for integrating into pipelines
• Troubleshooting - Common issues and solutions
• Security & Support - Security practices and support policy
• Development Guide - For contributors
• Examples - Real-world workflow examples

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Release Process

This project uses an automated release workflow. Releases can be triggered manually via GitHub Actions.

Creating a Release

1. Go to Actions → Release workflow
2. Click Run workflow
3. Configure the release options:
   • Version type: Choose patch, minor, or major for auto-increment
   • Custom version: Optionally specify an exact version (e.g., 2.1.0)
   • Pre-release: Check to mark as pre-release
   • Dry run: Check to test without creating a release

Version Increment Examples

Current Version	Version Type	Next Version
v1.0.0	patch	v1.0.1
v1.0.0	minor	v1.1.0
v1.0.0	major	v2.0.0

Release Artifacts

Each release automatically:

• Creates a version tag (e.g., v1.2.3)
• Generates release notes from commits
• Updates the major version tag (e.g., v1)
• Updates the latest tag

For more details, see the Changelog Policy.

Acknowledgments

• GitHub CLI - The official GitHub command line tool
• GitHub Actions - GitHub's CI/CD platform