CLI Reference¶

gh ship <COMMAND>

Global options¶

Choosing the release line¶

preview, prepare, release and status accept:

With release lines configured, this selects the line. Without them it simply overrides the branch the Release PR targets.

gh-ship works the branch out for itself, in order:

1. --base <BRANCH>, or SHIP_BASE_BRANCH.
2. The GitHub Actions environment — the branch a pull_request targets, otherwise the branch of the run. A run on a tag names no branch and is not guessed at.
3. The local checkout's current branch, read from .git/HEAD. No git binary is needed and nothing is fetched or cloned.
4. The repository's default branch.

Detection only applies when branches is configured; otherwise the repository default branch is used, exactly as before. gh ship status always reports which source it used.

run also accepts --base, but takes its branch from the triggering event. An explicit base must agree with that branch; it cannot redirect an event to another release line.

Waiting¶

run, preview, prepare and release all block on a workflow run they dispatched, unless run, prepare or release is given --no-wait (prepare, release). Two environment variables cap how long they wait:

Both take a whole number of seconds. The appear timeout only covers the gap between dispatching and GitHub queueing the run, so it rarely needs touching.

Raising SHIP_RUN_TIMEOUT past an hour only makes sense with a PAT, or with a GitHub App whose credentials are given to gh-ship (see Authentication), which then replaces its own token. With an installation token minted by a workflow step, a publish workflow that takes longer than about 50 minutes cannot be waited on with a single token. Use gh ship release --no-wait instead, or retry with a fresh token.

When a command runs inside a workflow of your own, set an explicit job timeout-minutes. For graceful timeout handling and retries, each gh-ship wait must expire before the remaining job budget, with headroom for queueing, token refresh, and subsequent attempts. The retry examples in Workflows budget for this. A shorter job timeout is a hard cancellation instead: GitHub may terminate the command before it returns exit 75, so its retry logic cannot run.

The SHIP_RUN_TIMEOUT default of 3600 s is exactly the lifetime of a GitHub App installation token. Inside GitHub Actions, gh-ship warns when the timeout is at or above that, since a wait that long outlives the token. Lower it, and when it expires the command exits with code 75, which a workflow can retry with a fresh token. The warning does not appear when gh-ship mints its own token, since that one is replaced before it expires.

gh ship run¶

gh ship run [--base <BRANCH>] [--no-wait]

An automatic entry point for a single-job Ship workflow. It reads GITHUB_EVENT_NAME and the JSON payload at GITHUB_EVENT_PATH, with GITHUB_ACTIONS=true:

Tag pushes, branch deletions, and unconfigured branches also skip. PR identity is checked against GitHub, including when the payload omits its PR object but retains its number. A newer open Release PR cannot replace the triggering PR. Labels are not used for detection, and this command never merges a PR.

--no-wait is passed to the selected phase: prepare leaves its staging workflow running; release leaves publication pending. Re-running release can adopt its publish run. Re-running prepare starts a new preparation and sweeps the old staging ref, so allow enough time for one complete preparation. Manual dispatch and workflow_run events are not automatically routed; call prepare or release explicitly for those workflows.

Outside Actions, or when a supported event's payload is missing or malformed, the command fails with a diagnostic. Use gh ship prepare and gh ship release locally. --base / SHIP_BASE_BRANCH must match the event branch.

Authentication¶

Authentication is gh's job: gh auth login locally, GH_TOKEN in CI. gh-ship can instead act as a GitHub App, given its credentials:

gh-ship then mints an installation token, scoped to the repository, sets it as GH_TOKEN on every gh it runs, and replaces it before its one hour is up. Set both of the first two or neither. See Letting gh-ship mint the token.

Transient failures¶

GitHub occasionally answers a valid query with a 502 or 504 — most often on the GraphQL endpoint behind the --json flags — and is fine again seconds later. gh-ship retries those rather than failing the release:

Diagnostics¶

Only read-only calls are retried — list, view, status, download, diff, checks and GET requests to gh api. A gateway timeout means GitHub stopped answering, not that it stopped acting: a timed-out pr create may well have created the pull request, so retrying it would open a second one. Writes still fail on the first error, and are safe to re-run by hand because every gh-ship command is idempotent.

Rate limits are not retried either. They clear in minutes rather than seconds, so the error tells you to wait instead of spending the budget for nothing.

Colour¶

gh-ship colours its output when it believes something will render it, following the same variables as gh itself — there is no --color flag.

Otherwise gh-ship colours its output when stderr is a terminal, or when GITHUB_ACTIONS=true. Actions gives every process a pipe rather than a terminal but renders ANSI in its logs, so workflow output is coloured without any configuration.

Only the human-readable output on stderr is ever coloured. Stdout carries the machine-readable payloads — --json, and the rendered PR body from gh ship preview — and is never coloured, so it stays safe to pipe.

Exit codes¶

Code 75 is EX_TEMPFAIL from sysexits.h. It is distinct from 1 so a workflow can retry on this case alone — for instance with a fresh token — without treating a real failure, such as a failed or cancelled run, as retryable. A run that never appeared (SHIP_APPEAR_TIMEOUT) is not reported as a completion timeout and still exits 1.

gh ship init¶

Make a repository gh-ship enabled.

$ gh ship init [--force]

Scans .github/workflows/, lists the workflows gh-ship can dispatch, explains the ones it cannot, offers to generate templates, and writes a documented .github/ship.yml.

Requires an interactive terminal. In automation, write the config directly.

init is entirely local: it never contacts GitHub, so it needs no authentication and ignores --repo.

gh ship validate¶

Check a release artifact, or the setup.

$ gh ship validate [FILE]

With a file — validates it against the artifact schema. Requires no network, no repository, and no GitHub authentication.

Without a file — validates .github/ship.yml and checks that the workflows it names satisfy the contract. Requires no network and no GitHub authentication either.

$ gh ship validate ship.release.json
✔ ship.release.json is a valid release artifact
  version: 1.4.0
  tag: v1.4.0

gh ship preview¶

Dry-run the prepare workflow and render the Release PR.

$ gh ship preview [--json]

Dispatches the prepare workflow with dry_run: true, waits, downloads the artifact, and renders the PR: the body on stdout, the title, labels and rules on stderr. So gh ship preview > body.md captures exactly the PR body.

Nothing on GitHub is modified: no branch, no PR, no tag, no release.

gh ship prepare¶

Run the prepare workflow and open or update the Release PR.

$ gh ship prepare [--no-wait]

1. Stops if a merged Release PR is still awaiting gh ship release.
2. Sweeps staging branches left behind by earlier runs.
3. Cuts a throwaway staging branch, ship/prepare-<token>, from the base branch (workflow_dispatch needs the ref to exist). With release lines configured the name carries a SHA-256 identity of the full base name — ship/prepare-<hash>-<token>.
4. Dispatches the prepare workflow on that staging branch and waits.
5. Downloads and validates the artifact.
6. Stops with exit 0 if changed: false.
7. Moves the release branch onto the staged release commit, then sweeps again.
8. Opens or updates the Release PR, embedding the artifact in its body.

Re-running is safe, and is the supported way to refresh a Release PR: the release branch moves onto the new commit and the existing PR is updated in place.

gh ship status¶

Show where the current release stands.

$ gh ship status [--json]

A pure query. It dispatches nothing, waits for nothing, and changes nothing.

Everything is reconstructed from GitHub — branch, PR, last run, the artifact embedded in the PR body — so the answer is the same on any machine.

gh ship release¶

Tag, publish, and release the merged Release PR.

$ gh ship release [--merge] [--no-wait]

1. Finds the Release PR and recovers the artifact from its body.
2. Requires the PR to be merged (or merges it with --merge).
3. Tags the merge commit — never a remembered SHA, because a squash merge creates a new one.
4. Creates the GitHub Release as a draft.
5. Dispatches the publish workflow so it can attach assets — unless a run of it already succeeded for the tag, in which case it is skipped, or one is still in flight, in which case that run is adopted and waited on.
6. Makes the release visible.

Idempotent: if the release already exists, it is not recreated.

gh ship sign¶

Re-create a commit so GitHub signs it.

$ gh ship sign [BRANCH]

Meant for the prepare workflow, not for you: it re-creates the tip commit of BRANCH through the API, with the same tree, parents and message but no identity of its own, and moves the branch onto the result. GitHub signs a commit it creates for a bot, so the commit comes out Verified where git commit cannot.

BRANCH defaults to the branch the workflow was dispatched on — the staging branch — read from GITHUB_REF, or from the checkout outside CI.

$ gh ship sign
▶ signing ship/prepare-8f2c1a9e4b07 at c0ffee0
✔ signed as 51c8ed0

Two behaviours worth knowing:

• A commit whose signature is already verified by GitHub is left alone and the command succeeds. The check uses GitHub's verification status, not merely the presence of a signature; an unverified signature may be replaced.
• When GitHub returns the re-created commit unsigned, the command fails and the branch is not moved. That happens when the token is not a bot — a PAT or a user login cannot produce a signature, whatever its permissions — and moving the branch anyway would change the commit's author for no benefit.

Needs contents: write. See Getting a verified release commit for where it fits in a workflow, and for the alternatives.