I built a CLI that checks whether your release notes match what actually shipped

Kevin — Fri, 25 Sep 2026 02:09:13 +0000

Most release notes are generated from the tag. Squash-merge subjects, PR titles, maybe a conventional-commit parser. The output always matches the tag because the tag is the input.

That's fine for a changelog. It doesn't answer a harder question: did the release claim match what actually shipped?

A release claim comes from somewhere else — a Jira board, a GitHub project, a spreadsheet someone maintains. It says "v2.4 contains PROJ-101, PROJ-102, and PROJ-103." The question is whether that's true. Did all three land? Did anything else land that nobody mentioned?

I built Shipledger to answer that.

What it does

Shipledger walks the commit range between two tags and reconciles what it finds against a changeset file you provide. The changeset lists the items you claimed shipped. The CLI checks whether git agrees.

It runs locally. No GitHub API calls, no network access, no tokens. Just your repo on disk.

Two things can go wrong:

A commit has no matching item. Something shipped that the release doesn't claim. Shipledger calls this unknown-reference.
An item has no matching commit. The release claims work that isn't in the tag. Shipledger calls this items-without-commits.

Both are findings. Whether they're problems depends on context — but now you know about them.

A concrete example

I set up a demo repo with two releases to show both outcomes.

v0.2.0 claims two items: #1 (Add widget) and #2 (Handle empty input). Both commits appear in the v0.1.0..v0.2.0 range. The check passes:


bash
npx shipledger check \
  --config shipledger.config.json \
  --changeset changesets/v0.2.0.json \
  --out verified-v0.2.0.json
## exit 0 — pass

DEV Community: Kevin

I built a CLI that checks whether your release notes match what actually shipped

What it does

A concrete example