Installation¶

gh-ship is a GitHub CLI extension, and that is the only way it is distributed.

$ gh extension install noirbizarre/gh-ship

Upgrade:

$ gh extension upgrade ship

You get gh ship, using the GitHub authentication you already have. There is no separate binary to download, no package on crates.io, and nothing to keep in sync.

In GitHub Actions¶

Install the extension in jobs that run orchestration commands or sign release commits. Runners already have gh and a token, so installing is one line:

- name: Install gh-ship
  env:
    GH_TOKEN: ${{ github.token }}
  run: gh extension install noirbizarre/gh-ship

The orchestrator validates the release artifact after downloading it. Preparation only needs to write and upload it; Release PR CI builds and tests the changes.

Validation is fully self-contained

Installing needs gh, but running gh ship validate FILE does not need much of anything: no network access, no repository, and no GitHub authentication. The schema is embedded in the binary.

So it is safe as the very first step of any job, and the check itself works on any CI system. This is enforced by a test that runs it with an empty PATH, no token variables, and a working directory that is not a git repository.

Requirements¶

The GitHub CLI.
Authentication: gh auth login locally, or GH_TOKEN in CI (or a GitHub App's credentials, which gh-ship turns into a self-refreshing token). See what the token must be allowed to do.
Release workflows that declare on: workflow_dispatch — see Workflows.

Building from source additionally needs Rust 1.88 or later, the rust-version declared in Cargo.toml.

Building from source¶

You do not need this to use gh-ship. Its own workflows install the published extension for orchestration and signing, while PR CI builds and tests the changes and the publish workflow builds release binaries. Before its own first release existed it had no choice but to bootstrap —

- run: cargo build --release
- run: ./target/release/gh-ship prepare

— because an extension cannot install itself before there is anything to install. That has not been necessary for some time.