How ShipNotes works

What triggers a changelog draft?

A published GitHub release — or a pushed tag, as a fallback — triggers generation. The ShipNotes GitHub App subscribes to release, push, and installation events; every webhook delivery is verified with an HMAC-SHA256 signature and deduplicated by delivery ID, so replays and forged requests are rejected. You never call an API or add a CI step: the trigger is the release workflow you already have.

How does ShipNotes know what changed in a release?

ShipNotes computes the range between your new release and the previous one, then collects every pull request merged inside that range. PR titles, descriptions, and labels carry far more human context than raw commit messages — that context is what makes the generated notes read like a person wrote them.

This is also why ShipNotes does not require conventional commits: the source material is what your team already writes in PRs, not a commit-message convention you would have to enforce first.

How does the AI write the release notes?

The merged PRs are handed to a language model with your repository's voice and format settings. The model groups changes into Features, Fixes, and Improvements, drops noise (dependency bumps, internal chores), and phrases each entry for your configured audience — developer-facing or end-user-facing. Generation runs once per release and the result is stored, so regenerating is cheap and nothing is sent to third parties beyond the LLM call itself.

Do I review the notes before they go out?

Yes — nothing is published without you. Each release produces a draft you can edit inline or publish as-is with one click. Teams typically publish drafts unchanged after the first couple of releases, once the voice settings are dialed in. Both the generated and the edited versions are kept, so you can always see what the AI proposed.

Where do published notes go?

Publishing fans out to every distribution channel at once:

• Hosted changelog page — a public, themeable page at your ShipNotes slug, updated within minutes (server-rendered with incremental revalidation)
• RSS feed — standard RSS 2.0 per changelog page
• Email — subscribers get the new entry in their inbox
• Slack — an optional webhook posts the entry to your channel

What access does ShipNotes have to my code?

Read-only, least-privilege access: repository contents (to resolve release tag SHAs), pull requests, and repository metadata. ShipNotes cannot push, merge, or modify anything in your repositories. Installation tokens are encrypted at rest, and uninstalling the app immediately deactivates its repositories. Details are in the getting started guide.

Related reading

• Getting started — the four-step setup
• From conventional commits to changelog — how the PR-based approach compares to commit-convention pipelines
• How to write release notes users actually read