@tryghost/pro-ship

Pro Ship

Ship a Ghost(Pro) package: bump the version, update the production Kubernetes deployment image tag when one exists, commit, tag, push — and optionally publish to the registry.

Install

pnpm add --save-dev @tryghost/pro-ship
# or
npm install --save-dev @tryghost/pro-ship

What it does

Run from a clean working tree on the default branch (i.e. main), pro-ship performs a release end to end:

1. Verifies the git working tree is clean (aborts otherwise).
2. Verifies you are on the repo's default branch (aborts otherwise).
3. Bumps the version in package.json (without letting the package manager create its own commit or tag).
4. Updates the image tag in k8s/overlays/production/deployment.yml when that file exists.
5. Commits the changes (package.json, the lockfile, and the manifest) as vX.Y.Z.
6. Creates an annotated vX.Y.Z tag and pushes with --follow-tags.
7. If --publish is set, runs <package-manager> publish.

CI/CD deploys off the pushed tag, so the tag format (vX.Y.Z) is stable.

The default branch is resolved from origin/HEAD rather than assumed to be main or master, so main/master naming is handled automatically. git clone sets origin/HEAD for you; in the rare case it is missing, the release aborts with guidance to run git remote set-head origin --auto.

Choosing the version

Pass a release type or an explicit version as an argument, or run with no argument to choose interactively:

# Interactive picker (patch / minor / major / custom), previews each result
pnpm exec pro-ship

# Release type
pnpm exec pro-ship minor

# Explicit version
pnpm exec pro-ship 1.2.3

• A release type is one of major, minor, patch, premajor, preminor, prepatch, or prerelease.
• An explicit version must be valid semver without build metadata — the +build suffix is rejected because it cannot appear in a deployment image tag. Prerelease tags (1.2.3-beta.1) are fine.
• The interactive picker requires a TTY. In non-interactive contexts (such as CI) pass the release type or version as an argument; otherwise the run fails with usage guidance.

Package manager support

The version bump (and publish) run with the repository's own package manager — pnpm, npm, or Yarn Classic (1.x) — resolved in this order:

1. The corepack packageManager field in package.json.
2. The lockfile on disk (pnpm-lock.yaml, yarn.lock, package-lock.json).
3. Defaulting to yarn for legacy consumers with no detectable signal.

A packageManager field naming an unsupported manager — including Yarn Berry (yarn@>=2), whose yarn version lacks the flags this tool relies on — fails fast rather than guessing.

Publishing

Publishing is opt-in via --publish. When set, pro-ship runs <package-manager> publish after the release commit and tag are pushed.

npm refuses to publish a package whose package.json sets "private": true, so pro-ship enforces the same rule up front: passing --publish for such a package fails before any git mutation. This is the npm private field, not repository visibility — a package in a private GitHub repository still publishes to npm as long as it isn't marked "private": true. (Pro-Packages itself is a private repo whose @tryghost/* packages publish publicly; only the monorepo root sets "private": true, to keep the workspace root off the registry.)

Whether a repo publishes is a property of the repo, not of each release, so wire the flag into the package's own ship script rather than typing it each time (typing it on the command line also trips the pnpm/npm run -- separator):

// publishable library
{ "scripts": { "ship": "pro-ship --publish" } }

// deploy-by-tag service (no publish)
{ "scripts": { "ship": "pro-ship" } }

With that in place, a release is just pnpm ship (interactive) or pnpm ship minor (non-interactive).

Develop

This is a monorepo package. Follow the instructions for the top-level repo.

1. git clone this repo & cd into it as usual.
2. Run pnpm install to install top-level dependencies.

Test

• pnpm --filter @tryghost/pro-ship lint runs lint.
• pnpm --filter @tryghost/pro-ship test runs lint and tests.

Copyright & License

Copyright (c) 2013-2026 Ghost Foundation - Released under the MIT license.