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:

• What new features were added?
• What changed?
• Is it safe to upgrade?

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.

In this article, I will walk through the changes from v0.1 and what I am planning next.

Let’s take a look!

🤖 What is changelog-bot?

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:

• Collect commits and PRs from the previous release to the current release
• Categorize changes into sections such as Added, Changed, Fixed, Docs, and Chore
• Add a new release section to CHANGELOG.md
• Create a Pull Request with that change

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.

🐾 What was available up to v0.1

Up to v0.1, I focused on building the foundation of changelog-bot.

It already supported:

• CLI and GitHub Action usage
• Changelog generation from Git history
• Importing GitHub Release Notes
• OpenAI and Anthropic providers
• Heuristic fallback
• Dry-run mode

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:

• “Write it in Japanese.”
• “Group internal changes under Chore.”
• “Group dependency updates together.”

So the customization experience was still weak.

🚀 v0.2: Gemini provider support

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.

🚀 v0.3: Changelog customization

In v0.3, I added customization support for changelog generation.

The newly added options are:

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.

🥌 Roadmap toward v1

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.

1. Config file support

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.

2. Choosing behavior when an AI provider fails

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:

• “Fail when AI generation fails”
• “Fallback and continue”

Both behaviors are valid depending on the project.

3. JSON report output

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:

• provider
• model
• aiUsed
• fallbackReasons
• generated sections
• PR title
• labels

This should make it easier to integrate changelog-bot with other CI tools and bots.

4. Better changelog quality

I also want to keep improving the quality of the generated changelog.

Some areas I want to improve are:

• Grouping dependency updates
• Detecting breaking changes
• Label-based include / exclude rules
• Custom section names
• Better duplicate detection

Especially in OSS, what should be included in a changelog differs from project to project.

I want changelog-bot to handle those differences better.

🎯 Summary

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 AI.

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!

Now let’s auto-generate our CHANGELOG.md files and use the saved time to play some games! 🧟🍀