The work is done. The tests pass. Now you only need to release it.
So you open package.json and change 1.4.0 to 1.5.0. You run npm install so the lock file follows. Then:
git commit -am "chore: release v1.5.0" git tag v1.5.0 npm run build git push origin main --tags gh release create v1.5.0 dist/*.tgz --generate-notes npm publish It works. But look at what can go wrong.
The build fails after the tag. Now you have a release commit and a tag for a version that does not exist, and you undo them by hand. Or git push is rejected, because a teammate pushed first. Or you forget the lock file, and the next person sees a dirty tree.
So you write a release.sh. Then the next repo is Python, so it gets its own release.sh. The Go one tags and does nothing else. The Rust one is half copied from the npm one. 😅
After a few years, every repo has its own way to ship, and you have to read the script each time to remember it.
One flow for every repo
shipo (Ship out of the box) is that script, written once, for every stack. You run one command:
$ shipo javascript (1.4.0) patch → 1.4.1 ❯ minor → 1.5.0 major → 2.0.0 current → 1.4.0 ✓ bump minor · 1.4.0 → 1.5.0 ✓ checks tools, tree, remote, build ✓ version package.json → 1.5.0 ✓ commit chore: release v1.5.0 ✓ tag v1.5.0 ✓ build [1/1] npm run build ✓ push origin/main + v1.5.0 command npm publish Run? [y/N] y ✓ command [1/1] npm publish And each repo says what is different about it in a small file, .shipo:
# .shipo [version] preset = "javascript" [build] command = ["npm ci", "npm run build"] [publish] push = "origin/main" release = "dist/*.tgz" command = "npm publish" You don't start from zero. shipo init finds your stack and writes a first .shipo for it.
| By hand | With shipo |
|---|---|
| edit the version, refresh the lock | the preset finds it; the lock is refreshed |
| commit and tag, with the right message | chore: release v1.5.0, tag v1.5.0 |
| a failed build leaves a broken tag | the commit and tag are undone |
| a rejected push, found at the end | checked first, before anything changes |
a different release.sh in each repo | the same flow, a few lines of config |
One flow for every repo. The differences live in
.shipo.
Local is undone, remote is never
This is the one idea the whole tool is built on. A release has two halves:
🛡️ Everything before publish is local. The checks run first and change nothing: the tools are there, the tree is clean, the tag is free, and the push will fast-forward. Then the version is written, committed, and tagged, and the build runs. If any of that fails, the commit and the tag are undone. Even after Ctrl-C.
📤 Publish leaves your machine. A pushed tag, a GitHub Release, a package on npm: those can't be taken back safely. So shipo doesn't try. It runs them one by one, and asks before each one that goes beyond git push:
✓ push origin/main + v1.5.0 release v1.5.0 + dist/*.tgz Create? [y/N] y ✓ release v1.5.0 + 3 file(s) command npm publish Run? [y/N] n - command skipped If a publish step fails, nothing is undone. You fix the problem and run only that step again:
shipo check # where does this release stand? shipo command # run the missing step shipo check shows the plan before a release, and where a release stopped after one:
$ shipo check checks ✓ tools gh, git, npm ✓ remote origin/main, fast-forward ok release v1.5.0 ✓ tag local, remote ✗ release not created plan push origin/main + v1.5.0 release v1.5.0 + dist/*.tgz command npm publish Undo what you can. Ask before what you can't.
On top of your tools
shipo does not build, pack, or upload anything itself. It runs the tools you already use, in the right order:
| Part | Who does the work |
|---|---|
| version | shipo: it reads and writes the version text only |
| bump | shipo, with git: commit and tag |
| build | your commands: npm run build, go test, docker |
| push | git: commit and tag in one atomic push |
| release | gh: a GitHub Release, notes, and files |
| workflow | gh: start an Actions workflow and wait for it |
| command | your commands: npm publish, cargo publish, a deploy |
Presets know where the version lives in each stack: package.json, pyproject.toml, Cargo.toml, composer.json, pubspec.yaml, pom.xml, *.csproj, or git tags for Go and Swift. Only the version text is rewritten, so your formatting and comments stay.
For anything else, you give a file and a pattern:
[version] source = "internal/version.go" pattern = '/const Version = "{version}"/' One more thing: commands run without a shell, the same way on macOS, Linux, and Windows. No &&, no pipes, no $VAR. If you need those, put them in a script and run the script. It is a small limit, and it means a .shipo works the same on every machine.
A few configs
A Go CLI. The tag push starts your release workflow, so this is all:
[version] preset = "go" [build] command = ["go vet ./...", "go test ./..."] A Python package:
[version] preset = "python" [build] command = "uv build" [publish] release = "dist/*" command = "uv publish" A Docker app. The workflow builds the image, shipo waits for it, then deploys:
[version] source = "VERSION" pattern = "{version}" [publish] workflow = "image.yml version={version}" command = "ssh deploy@203.0.113.10 'cd /app && export TAG={version} && docker compose pull && docker compose up -d --wait'" In a monorepo, each folder has its own .shipo and its own tags, like api/v1.2.3 and web/v1.2.3. shipo finds them all and asks which one to release.
Two release lines
Some projects ship a stable main and a next beside it. shipo adds the branch name to the version:
[bump] suffix = "next" [publish] push = "{remote}/{branch}" release = true | Branch | 1.2.0 + minor | Tag |
|---|---|---|
main | 1.3.0 | v1.3.0 |
next | 1.3.0-next | v1.3.0-next |
When next is ready, shipo final on next does the round trip: it switches to main, brings in the commit you tested, releases 1.3.0, brings the release back into next, and switches back.
It releases what was tested: the commit of the last -next tag, not whatever next holds now. Newer commits stay on next, out of the release.
For agents too
The flow with the menu is for a person. But every part also runs on its own, with no prompt:
shipo bump patch shipo build shipo push shipo release shipo command So an AI agent can release too, one step at a time. shipo skill claude user installs a skill for Claude Code (also Codex, Cursor, and Copilot). The skill tells the agent to read the project, write .shipo, run shipo check until it passes, show you the plan, and ask you before each publish step. It never runs the interactive flow, because that flow needs a person.
The agent writes the config and does the steps. You still say yes before anything leaves your machine.
What shipo is not
To be honest about it, here is where it stops:
| Good fit | Not a fit |
|---|---|
versions like MAJOR.MINOR.PATCH | dates or build numbers as versions |
| a person choosing the bump | the bump chosen from commit messages |
| releasing from your machine, you or an agent | releasing only from CI |
| each folder of a monorepo on its own | many packages released together in one step |
- It is not CI. What runs on GitHub stays in GitHub Actions. shipo can start a workflow and wait for it.
- It does not pick the bump. If you want that from commit messages, semantic-release and release-please do it well, in CI.
- It does not write a changelog. A GitHub Release gets the notes GitHub generates from the commits.
And one honest note: shipo is young. The first commit is from November 2026, and most of it was written in a week. It releases itself with its own .shipo. If your release has a case it does not cover, open an issue.
Give it a try
brew install diphyx/tap/shipo # or go install github.com/diphyx/shipo@latest Then, in the folder you release:
shipo init # write .shipo for your stack shipo check # see what a release would do; changes nothing shipo # choose the bump, then release It needs git. gh, logged in, is needed only for GitHub Releases and workflows.
If you have a release.sh in every repo, and each one is a little different, that is exactly what shipo is for.


