ShipNotesWrite notes

How ShipNotes writes release notes from your GitHub commits

ShipNotes is a free web tool that turns the commits and merged pull requests between two refs of a public GitHub repo into release notes. It groups the changes, writes each one as a single line for users and for developers, and links every line to the pull request or commit it came from.

It works on public repos only, reads at most the newest 150 commits in a range, and allows 4 new runs per hour from one IP address. There is no sign-in.

The steps

  1. Pick a repo and two refs. Enter owner/repo or a github.com URL. The server reads up to 40 of the repo's releases or tags and fills in the two newest stable ones when there are two. You can type any tag, branch name or commit SHA instead.
  2. Fetch the commits. The server calls the GitHub REST compare endpoint for base...head. PR numbers come from squash commit subjects like fix: x (#123) and from merge commits, and every commit brought in by a merge is credited to that PR. PR titles, descriptions, labels and authors come from one GitHub search, with single PR lookups as a fallback. When the server has a GitHub token, commits with no PR number are also checked against GitHub's list of PRs for that commit.
  3. Write the notes. One call to the OpenAI Responses API with Structured Outputs (gpt-5.4-mini by default) returns a headline, a summary and a list of bullets. Each bullet has a category, a line for users, a line for developers and the IDs of its sources. PR text is passed to the model as untrusted data, and the prompt tells it to ignore instructions inside it.
  4. Check every citation. Code resolves each cited ID against the commits and PRs it fetched. Made up PR numbers and SHAs are dropped, a bullet left with no valid source is removed, and any change the model skipped is added back from its own title, with its category picked from conventional commit prefixes and labels. The result of these checks is shown under the notes.
  5. Export. Copy the markdown, download it as a .md file, or open the draft release body, which renders the markdown the way a GitHub release page shows it.

How changes are grouped

Every bullet lands in one of six groups, shown in this order:

  • Breaking changes. Removes or changes behavior users depend on, so upgrading needs action.
  • Features. A new capability.
  • Improvements. Better behavior or performance of something that already existed.
  • Fixes. Bug fixes.
  • Docs. Documentation only.
  • Internal. CI, tests, dependency bumps, refactors, release chores and tooling. Hidden unless you turn on the Internal switch.

For users or for developers

The same model call writes two versions of every line. For users describes what changed for someone using the library or app. For developers keeps the technical detail. The switch above the notes only picks which version to show, so changing it makes no new request, and the copied or downloaded markdown follows whichever version is selected.

How each line links back

In the page, each line shows the PR number or commit SHA it came from, linked to GitHub. In the markdown, lines follow GitHub's release format: - line by @author in <PR url>, or the commit SHA when there is no PR. GitHub turns both into links. The markdown ends with a contributors line, leaving out bots, and a Full Changelog link to the compare view for the range.

Browser and server

The browser sends only the repo name and the two refs. The server calls GitHub and OpenAI, so the OpenAI key and any GitHub token never reach the browser. Progress and the result stream back line by line. The tone switch, the Internal switch and the markdown are handled in the browser from that one result.

Limits

Commits per range
The newest 150 commits between the two refs are read. Older commits in a larger range are left out.
Note runs
4 new runs per IP address per hour. A range someone generated in the last hour comes back from cache and does not count.
Tag lookups
20 per IP address per hour.
GitHub quota
The server shares one GitHub quota: 60 requests per hour without a token, 5,000 with one. When it runs out, ShipNotes stops calling GitHub and tells you when it resets.
Prompt size
About 48,000 characters. PR descriptions start at 500 characters each and are shortened, then dropped, until the prompt fits. Titles are always kept.
Model call
Low reasoning effort, up to two retries and a 90 second timeout.
Request size
Request bodies over 2 KB are refused.

What is sent and what is kept

OpenAI receives the repo name, the range, and for each change its title, labels, author login and a shortened PR description. Code diffs are not sent.

GitHub responses are kept in server memory for 15 minutes and finished notes for one hour, so a repeat request for the same range is answered from memory. To enforce the hourly limits, Redis keeps a request count keyed by IP address, which expires with the hour. Repo names, refs and notes are not written to any database, there are no accounts, and the page saves nothing in your browser.

Try a sample

The home page has three sample ranges, each a pair of adjacent stable releases:

  • pmndrs/zustand v5.0.14 to v5.0.15, state management for React
  • sindresorhus/ky v2.0.2 to v2.1.0, tiny fetch-based HTTP client
  • axios/axios v1.19.0 to v1.20.0, promise-based HTTP client

Open ShipNotes and write notes