Hoi hoi!
I’m @nyaomaru, a frontend engineer who recently discovered the deliciousness of a cheese whose name sounds a bit like Al Capone.
Are you building personal projects?
Or contributing to OSS?
Or maybe you are busy playing Resident Evil 9 🧟 and CloverPit 🍀?
Whatever the case, I respect your admirable dedication as an engineer.
Now, when managing OSS on GitHub, one file that becomes very important is CHANGELOG.md
.
Why is it important?
For example, when a library I use gets updated, the first thing I usually check is CHANGELOG.md
.
Recently, I have been experimenting with an AI triage workflow. For Dependabot updates, I feed release notes and CHANGELOG.md
into AI, then ask Claude Code to evaluate the risk and help with triage.
This has been very useful. I do not have to check everything manually, and that makes me happy 😺
In other words, CHANGELOG.md
is becoming a document that is not only read by humans, but also read by AI as input for dependency update decisions.
So, CHANGELOG.md
will continue to be very useful in the coming era.
But surprisingly, many projects do not maintain it well.
For example, even some very useful React development tools sometimes ship silent releases without any release notes at all.
When that happens, users have to dig through commit history and figure out things like:
Of course, busy engineers do not have time for that. I am not that busy, but if I had that time, I would rather play CloverPit 🍀.
So, to protect my precious game time, I built an OSS tool that automatically generates CHANGELOG.md
.
Releases should feel exciting, not tedious
@nyaomaru/changelog-bot
🤖 turns your Git history and release notes into a polished changelog entry (and optional PR) in a single run. Drop it into CI, run it locally, or hand it to your release captain—either way, you ship with a crisp changelog and zero copy-paste fatigue.
Important
This project is currently in its early stages…
In this article, I will walk through the changes from v0.1 and what I am planning next.
Let’s take a look!
changelog-bot is a CLI and GitHub Action that automatically creates a Pull Request to update
CHANGELOG.md
based on Git history, Pull Requests, and GitHub Release Notes.What it does is simple:
Added
, Changed
, Fixed
, Docs
, and Chore
CHANGELOG.md
If you configure an AI provider, it can use OpenAI
, Anthropic
, or Gemini
to generate a more readable changelog section.
On the other hand, it also works with a fallback mode when no API key is provided.
So it is totally fine even if you do not use AI.
In other words, this is not:
A tool that can do nothing without AI.
It is more like:
An automation tool that works better with AI.
That is the key idea.
Up to v0.1, I focused on building the foundation of changelog-bot.
It already supported:
At this point, the basic experience was already there:
Automatically update
CHANGELOG.md
during a release workflow.
I also introduced it in this earlier article:
https://zenn.dev/nyaomaru/articles/introduce-changelog-bot
But there were still some problems.
In particular, even though users could choose an AI provider, there was still no strong way to adjust the language or writing style of the generated CHANGELOG.md
for each project.
For example, there was no good way to pass project-specific rules such as:
So the customization experience was still weak.
In v0.2, I added Gemini as a new LLM provider.
Now changelog-bot supports these three providers:
OpenAI
Anthropic
Gemini
You can specify Gemini from the CLI like this:
changelog-bot \
--provider gemini \
--release-tag HEAD \
--release-name 0.2.0 \
--dry-run
You can also use it from GitHub Actions:
with:
provider: gemini
env:
GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
I also added dry-run diagnostics.
Provider: gemini
Model: gemini-3.5-flash
AI used: true
Fallback reasons: none
This makes it easier to check whether the AI provider was actually used, or whether changelog-bot fell back to the heuristic mode.
It is a small feature, but I think this kind of observability is very important for CI tools.
When something runs in CI, you want to quickly understand what actually happened.
In v0.3, I added customization support for changelog generation.
The newly added options are:
| Option | Description |
|---|---|
--language |
|
Specifies the language of the generated CHANGELOG.md |
|
--instructions |
|
| Passes inline instructions to the AI | |
--instructions-file |
|
| Passes instructions to the AI from a file |
For example, if you want to generate a changelog in Dutch, you can write:
changelog-bot \
--provider gemini \
--release-tag HEAD \
--release-name 0.3.0 \
--language nl \
--instructions "Schrijf kort en duidelijk in het Nederlands. Groepeer interne wijzigingen onder Chore." \
--dry-run
You can also define project-specific rules in a file.
changelog-bot \
--provider openai \
--release-tag HEAD \
--release-name 0.3.0 \
--language nl \
--instructions-file .github/changelog-instructions.md \
--dry-run
For example, .github/changelog-instructions.md
can contain rules like this:
Write concise release notes in Dutch.
Rules:
- Focus on user-facing changes.
- Group internal refactors under Chore.
- Group dependency updates together.
- Avoid mentioning commit hashes.
With this, changelog-bot is no longer just “a tool that generates changelogs with AI.”
It is moving toward:
A tool that can generate a
CHANGELOG.md
that feels right for each project.
Also, when customization is enabled, changelog-bot does not simply use GitHub Release Notes as-is, even if they exist.
Instead, it passes them to the model and lets the model rewrite them.
This means GitHub Release Notes can still be used as source material, while the final output reflects the specified language
and instructions
.
With customization added in v0.3, the shape of v1 is becoming much clearer.
Here are the main things I want to add before v1.
Passing CLI options every time is annoying, so I want to support config files.
{
"provider": "gemini",
"language": "nl",
"instructionsFile": ".github/changelog-instructions.md"
}
The goal is to make the same configuration usable from the CLI, GitHub Actions, and reusable workflows.
Right now, changelog-bot falls back when an AI provider fails.
This is convenient, but some projects may want the workflow to fail if AI generation fails.
So I am considering options like:
--fail-on-llm-error
--require-provider
--no-ai
Since changelog-bot is intended to be used in CI, users should be able to choose between:
Both behaviors are valid depending on the project.
Dry-run diagnostics already exist, but I also want to add a JSON report.
changelog-bot --dry-run --report-json
For example, it would be useful to output machine-readable information such as:
This should make it easier to integrate changelog-bot with other CI tools and bots.
I also want to keep improving the quality of the generated changelog.
Some areas I want to improve are:
Especially in OSS, what should be included in a changelog differs from project to project.
I want changelog-bot to handle those differences better.
CHANGELOG.md
is a very plain file, but for users, it is an important document.
Recently, it is also becoming more common to let AI read it and use it as input for dependency update decisions.
That is why CHANGELOG.md
should not just be generated somehow.
It should be generated in a readable way that fits each project’s context.
But writing it carefully by hand every time is honestly a pain.
changelog-bot is a tool for automating that process with Git history, Pull Requests, GitHub Release Notes, and
In v0.2, I added Gemini support.
In v0.3, I added customization through language
, instructions
, and instructions file
.
With these changes, changelog-bot is moving from:
Just generating a changelog automatically
to:
Generating a changelog that fits each project
v1 is getting closer.
If you are interested, please give the repository a ⭐ and watch over it warmly!
Releases should feel exciting, not tedious
@nyaomaru/changelog-bot
🤖 turns your Git history and release notes into a polished changelog entry (and optional PR) in a single run. Drop it into CI, run it locally, or hand it to your release captain—either way, you ship with a crisp changelog and zero copy-paste fatigue.
Important
This project is currently in its early stages…
Now let’s auto-generate our CHANGELOG.md
files and use the saved time to play some games! 🧟🍀