How to Publish a Changelog From GitHub

Your GitHub history already contains everything a changelog needs. The problem is that it contains it in the wrong language, at the wrong grain, mixed with hundreds of changes no customer will ever notice.

There are four common ways to close that gap. They are not equally good, and the right answer depends almost entirely on who reads the result.

Option 1: GitHub Releases

Tag a release, write notes, publish. GitHub will even generate a first draft from merged pull request titles.

Good for: open source projects, developer tools, CLIs, libraries — anywhere the audience is already on GitHub and comfortable reading pull request titles.

Bad for: commercial products with non-technical customers. The notes live on github.com rather than your domain, which means they don’t build your search presence, they aren’t styled like your product, and your customers will never think to look there.

Option 2: A CHANGELOG.md in the repository

The convention documented by Keep a Changelog: one Markdown file, Added / Changed / Fixed / Deprecated headings, updated as part of the pull request that makes the change.

Good for: keeping the changelog honest. Writing the entry while the change is fresh, in the same pull request, is the single most reliable way to stop entries from being reconstructed later from memory. It also gives you a real review flow — comments on a text diff instead of screenshots of drafts pasted into tickets, which is what review becomes in tools where a draft is only visible to its author.

Bad for: reaching anyone outside the repository. A file in a repo is not a published changelog. Most teams that stop here eventually build a page that renders the file, at which point they discover that entries written for a repository don’t read well as customer communication.

Option 3: A generator in CI

Tools like git-cliff, release-please, or standard-version parse conventional commit messages and produce a changelog on every release. Wire one into a GitHub Action and the file updates itself.

Good for: versioned software with disciplined commit conventions. It is accurate, it is free, and it never forgets.

Bad for: anything a customer reads. The output is your commit messages, reorganized. fix(sync): handle null cursor on paginated fetch becomes a bullet point, and the customer who lost their comments last Tuesday still has no idea that this is the line that says it’s fixed. Generation solves recall. It doesn’t solve translation.

Option 4: An agent that drafts from history

Connect the repository to an agent that reads commits and pull requests, groups related work, decides what is customer-visible, and writes each entry in plain language for a human to approve.

This is not the commit-dump-into-a-chatbot experiment, which fails the same way for everyone who tries it: the model weights whatever produced the most pull requests, so the Python 2-to-3 migration becomes the headline while the fix customers actually noticed gets a bullet — all delivered in a tone of enthusiasm nobody believes. A product lead at an observability company told us exactly that story: the migration ran through months of their internal notes and, correctly, never earned a word in their public changelog. An agent has to score customer impact, not activity, and that takes context about the product and who uses it.

This is what the Changebot Agent does. It connects to GitHub or Bitbucket, reads your history, and drafts updates in your categories and voice. You edit, you approve, and it publishes.

Good for: products with customers who are not developers, teams shipping faster than anyone can write, and anyone whose changelog is currently three weeks behind.

The tradeoff: a draft is a draft. The agent decides what looks customer-facing, and sometimes it will include something you consider internal or miss context that never made it into a commit message. Review is part of the workflow rather than a formality, which is why publishing stays behind human approval.

Publishing the result

Wherever the entry comes from, it still needs somewhere to land — and this is where the third system creeps in. Plenty of teams run an app repo, a marketing-site repo, and a changelog tool that talks to neither, which guarantees the changelog is the surface that goes quiet. A changelog that reaches people usually has four:

1. A public page on your own domain. Crawlable, dated, and yours — so it accumulates search and AI-assistant visibility instead of donating it to github.com.
2. An in-app widget. The people most likely to care are already using the product. A changelog widget puts the update in front of them without an email.
3. A feed. RSS or Atom, so power users and internal tools can subscribe.
4. Slack or Discord. Both for customers in a shared channel and for your own support and sales teams, who need to know what changed before a customer asks them.

With Changebot, that whole publishing layer is free — hosted page, widget, custom domain, Slack, Discord, RSS, and MCP. The $99 per repository per month covers the agent that writes the drafts.

A workflow that holds up

Ask what a changelog costs and people count the writing — ten, fifteen minutes. The real bill is everything around it: working out what actually shipped, and copying the result into every place it needs to appear. That’s the fifteen-minute illusion, and it’s the part a workflow has to remove.

The version that survives contact with a busy sprint looks like this:

1. Ship normally. No new commit conventions, no changelog file to maintain by hand.
2. Once a week, have the agent draft the update from that week’s merged work.
3. Spend ten minutes editing: cut the internal items, fix the one entry that describes the implementation instead of the effect, add a screenshot to anything visual.
4. Approve, and let it publish to the page, the widget, the feed, and Slack at once.

The failure mode this avoids is the one every team knows: nobody publishes, because publishing starts with a blank page and a week of commits nobody wants to reread.

Related reading

• Release notes template: four formats you can copy
• Changelog examples: five formats and what makes them work
• Your commit messages were never meant for customers

Frequently Asked Questions

Can you generate a changelog from git commits?

Yes, and tools like git-cliff or release-please will do it from conventional commit messages. The output is accurate but written in engineering language, so it works for developers reading a repository and not for customers reading a product update.

Should you use GitHub Releases as your changelog?

GitHub Releases works well for open source and developer tools, where the audience already lives on GitHub. For a commercial product with non-technical customers it is the wrong surface: it is not on your domain, not styled like your product, and not somewhere customers think to look.

How do you publish a changelog automatically when you merge a pull request?

Trigger on the merge event, either with a GitHub Action that appends to a file and commits it, or with an agent or API call that creates a draft entry. Keep a human approval step before anything customer-facing goes live; fully automatic publishing turns merge noise into customer noise.

Do conventional commits make changelogs better?

They make generation reliable, which is not the same as making the changelog good. Conventional commits give you clean grouping and versioning; they do not turn 'fix(sync): handle null cursor' into a sentence a customer understands.