ghup

ghup is a command-line tool for managing GitHub repository content and refs (branches and tags) directly via the GitHub API, with a focus on enabling verified commits from build systems such as GitHub Actions or Jenkins.

Key Features

• Create, update, and delete repository content with verified commits via GitHub API
• Create and update both lightweight and annotated tags
• Synchronise arbitrary git refs, including fast-forward merges
• Resolve commit references to full SHAs
• Open pull requests for changes
• Smart context detection for repository and branch information
• 12-Factor app style configuration via flags, environment variables, or files
• No external dependencies required

Requirements

• A GitHub token with contents=write and metadata=read permissions (plus workflows=write if managing GitHub workflows)
• For verified commits, use a token derived from GitHub App credentials

Installation

Pre-built Binaries

Download binaries for all platforms from GitHub Releases.

Using Go

go install github.com/nexthink-oss/ghup@latest

Homebrew

brew install isometry/tap/ghup

GitHub Actions

- uses: nexthink-oss/ghup/actions/setup@v1

Configuration

ghup can be configured through:

1. Command-line flags
2. Environment variables (GHUP_*, with various fallbacks for CI tools)
3. Configuration files (various formats supported)

When run from a git repository, ghup automatically detects:

• Repository owner and name from the GitHub remote
• Current branch
• Git user information for commit trailers

See full documentation for details on configuration options.

Basic Usage

Managing Content

# Update a file
ghup content -b feature-branch -u local/file.txt:remote/path.txt

# Create a pull request with changes
ghup content -b new-feature -u config.json --pr-title "Update configuration"

# Create a pull request with auto-merge using merge method
ghup content -b feature-branch -u config.json --pr-title "Auto-merge update" --pr-auto-merge merge

# Create a pull request with squash auto-merge
ghup content -b feature-branch -u config.json --pr-title "Squash merge update" --pr-auto-merge squash

# Update existing PR title with new commits
ghup content -b feature-branch -u config.json --pr-title "Updated configuration" --pr-update

# Add, update, and delete files in one commit
ghup content -b updates \
  -u local/new-file.txt:new-file.txt \
  -d old-file.txt \
  -c main:existing-file.txt:new-location.txt

See content command documentation for more examples.

Creating and Managing Tags

# Create an annotated tag
ghup tag v1.0.0 --commitish main

# Create a lightweight tag
ghup tag v1.0.0 --lightweight

See tag command documentation for more examples.

Updating References

# Fast-forward a branch to match another
ghup update-ref -s main refs/heads/production

# Update GitHub Actions-style tags after a release
ghup update-ref -s tags/v1.2.3 tags/v1.2 tags/v1

See update-ref command documentation for more examples.

Resolving Commits

# Resolve a branch to its SHA
ghup resolve main

# Find all tags pointing to a specific commit
ghup resolve abc123 --tags

See resolve command documentation for more examples.

Deployments

# Mark dev deployment as pending
ghup deployment -c main --environment=dev/us-east-1 --state=pending

# Mark production deployment as as succesful
ghup deployment -c main --environment=prod/us-east-2 --state=success --production

Debugging

# View configuration and environment information
ghup debug

See debug command documentation for more details.

GitHub Actions

ghup offers ready-to-use GitHub Actions to simplify integration within your workflows:

Setup Action

The nexthink-oss/ghup/actions/setup action installs ghup and makes it available in your workflow:

- uses: nexthink-oss/ghup/actions/setup@main
  with:
    version: v0.12.0 # optional, defaults to 'latest'

Fast-Forward Action

The nexthink-oss/ghup/actions/fast-forward action updates refs to match a source commit:

- uses: nexthink-oss/ghup/actions/fast-forward@main
  with:
    source: main
    target: refs/heads/production
    # force: false # optional, defaults to false
  env:
    GITHUB_TOKEN: ${{ github.token }}

Use this action to implement true fast-forward merges or to create/update tags from specific commits.

See individual action READMEs for detailed usage examples and parameters.

Documentation

Detailed documentation for all commands is available in the docs/cmd directory:

• ghup: General command usage and configuration
• ghup content: Managing repository content
• ghup deployment: Creating deployments and deployment statuses
• ghup tag: Creating and managing tags
• ghup update-ref: Updating git refs
• ghup resolve: Resolving commit-ish references
• ghup debug: Debugging configuration and environment

Contributing

All contributions in the spirit of the project are welcome! Open an issue or pull request to get started.