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:

checks, version, bump and build run locally and are undone on failure; publish sends the release out and is never undone

🛡️ 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:

publish runs push, then release, workflow and command, one by one; push has no prompt, the other three ask first

✓ 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.

shipo final on next switches to main, brings in the tested tag by merge or replace, releases there, brings the release 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.

GitHub · Docs · Built by DiPhyx