DEV Community

Cover image for Generate CHANGELOG.md Automatically 🤖
nyaomaru
nyaomaru

Posted on

Generate CHANGELOG.md Automatically 🤖

#ai #typescript #ci #opensource

Hey everyone! Happy winter is upcoming! ⛄️

I’m @nyaomaru, a frontend engineer.

Today I’d like to introduce changelog-bot, a tool that automatically generates a polished CHANGELOG.md from your release notes! 🚀

🧪 Background

If you’re maintaining a project, you’ve probably used CHANGELOG.md to keep track of release details.
But let’s be honest—updating it manually with every version bump is tedious.

Sure, you can automate parts of it, but most generators produce unstructured or messy output.
That’s exactly the pain point that inspired changelog-bot!

https://github.com/nyaomaru/changelog-bot

🎁 Why changelog-bot?

  • 🖋 Automates the boring part — generating CHANGELOG.md
    • Uses AI to structure and format the changelog with high accuracy
    • Analyzes commit messages and PR titles to automatically categorize “fix”, “feat”, etc.
  • Works directly from release notes
    • No need for strict Conventional Commit rules
  • Works even without AI
    • Fallback logic builds changelogs accurately even without an API key

🔎 How to Use It

Try it instantly (npx / pnpx)

The easiest way to try it out is from the CLI using npx or pnpm dlx!

pnpm 

pnpm dlx @nyaomaru/changelog-bot \
  --release-tag v0.0.1 \
  --provider openai \
  --dry-run
Enter fullscreen mode Exit fullscreen mode

💡 Tip: Remove --dry-run to actually create a PR with your updated CHANGELOG.md!

If you want to enable AI-assisted formatting, set your API key beforehand:

For security reasons, .env files are not automatically loaded.
Please export your environment variables manually.

# For OpenAI users
export OPENAI_API_KEY=sk-xxxx   # Use OpenAI as the provider
export OPENAI_MODEL=gpt-4o-mini # Optional: specify a model

# For Anthropic users
export ANTHROPIC_API_KEY=sk-ant-xxxx
export ANTHROPIC_MODEL=claude-3-5-sonnet-20240620
Enter fullscreen mode Exit fullscreen mode

Setting up a local dev environment with mise

If you’d like to explore the source or contribute, set up Node and pnpm with mise:

mise install     # Installs Node 22 / pnpm 10.12
mise dev_install # Installs dependencies
mise build       # Compiles TypeScript
Enter fullscreen mode Exit fullscreen mode

Then, export your environment variables:

export REPO_FULL_NAME=your_name/your_repository_name # Target repository
export GITHUB_TOKEN=ghp_xxx                          # GitHub token
export OPENAI_API_KEY=sk-xxx                         # Optional: for AI formatting
Enter fullscreen mode Exit fullscreen mode

Finally, just run the CLI — make sure to set your version properly!

mise start \
 --release-tag v0.0.1 \
 --provider openai \
 --dry-run
Enter fullscreen mode Exit fullscreen mode

💡 Tip: Remove --dry-run to apply changes to your CHANGELOG.md via PR!

  • If no API key is provided, it falls back to commit log analysis
  • You can swap models by setting OPENAI_MODEL or ANTHROPIC_MODEL

Automate with GitHub Actions

Even easier—let GitHub Actions handle it.
Just drop a workflow like this under .github/workflows/ and your changelog will grow automatically whenever a release tag is pushed:

name: Auto Changelog

on:
  workflow_dispatch:
  push:
    tags:
      - 'v*'

jobs:
  changelog:
    uses: nyaomaru/changelog-bot/.github/workflows/changelog.yaml@v0
    with:
      changelog_path: CHANGELOG.md
      provider: openai
      release_tag: ${{ github.ref_name }}
      dry_run: 'false'
    secrets:
      REPO_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
Enter fullscreen mode Exit fullscreen mode

If you don’t want to expose AI keys, you can set dry_run: 'true' to post a draft changelog as a PR comment instead.

🌱 Distribution & Ecosystem

  • Available as an npm/pnpm CLI package (@nyaomaru/changelog-bot)
  • Also usable as a GitHub Action via the included action.yml
  • The fallback logic doesn’t require Conventional Commits — easy to drop into any repo
  • Issues and PRs are always welcome! Templates are ready, so feel free to leave feedback 😹

Future Plans

  • Support for local LLMs as changelog classifiers
  • Multi-language changelog output
  • Improved accuracy via preprocessing and better prompts

🎯 Summary

changelog-bot is both a CLI and a GitHub Action that automatically generates CHANGELOG.md whenever a release is triggered.

👉 https://github.com/nyaomaru/changelog-bot

If you like it, don’t forget to leave a 🌟 — it keeps me going! 😻

Bonus

I’ve also released another OSS project called is-kit — a utility for building powerful isXXX type guards in TypeScript.

https://github.com/nyaomaru/is-kit

Check out the related articles:

Top comments (3)

Collapse
 
kavinjeya profile image
Kavin Jey •

The tedium is real -- changelog-writing gets skipped most often not because devs are lazy, but because there's no frictionless "just do it" path in the flow. ChangelogBot nails the zero-friction part.

One distinction worth flagging for SaaS builders: CHANGELOG.md is primarily for contributors tracking what shipped in each version. The adjacent problem -- communicating changes to paying users who never open a git log -- calls for a different source. Those users want feature-level "what's new" rather than commit granularity, and merged PRs are the natural unit for that (each PR usually captures one meaningful change, with full context).

I've been building tryshiplog.io for this second use case. There's a free no-signup tool at tryshiplog.io/tools/github-changelog-generator -- paste any public GitHub repo URL and it formats the merged PRs into structured draft release notes instantly, no install needed. Comparing ChangelogBot's output against it is a decent way to see which granularity your audience actually wants.

Collapse
 
nyaomaru profile image
nyaomaru •

Thanks for sharing! 😸

I think this distinction is right. CHANGELOG.md is usually closer to the repo/contributor workflow, while paying users need a more curated “what’s new” view.

ChangelogBot is mainly trying to remove friction from the repo-side changelog flow, but the boundary is interesting. One area I’m working on is AI-based WHY extraction, so the output is not just “what changed” from commits/PRs, but can also capture why the change matters when that context exists in PRs or release notes.

And yes, granularity is the key point here.
Commits, PRs, and user-facing features are different lenses.
PR-level notes are often a strong source when the target audience is outside the repo.

I'll try to compare outputs with tryshiplog.io!

Collapse
 
nyaomaru profile image
nyaomaru •

I tried your nice web site! 👍

It looks fashionable and well organized.

I have a feedback that these PRs are not improvements. I think it should categorize as "chore" or "docs" or something.

On the other hands, my changelog-bot categorize these automatically like below.

Please use it once my changelog-bot 😸

github.com/nyaomaru/changelog-bot/...

## [v0.6.4] - 2026-07-05

### Added

- improve why template extraction by @nyaomaru in [#155](https://github.com/nyaomaru/changelog-bot/pull/155)

### Docs

- 0.6.3 by [bot] by @github-actions in [#154](https://github.com/nyaomaru/changelog-bot/pull/154)

### Chore

- Release: 0.6.4 by [bot] by @github-actions in [#156](https://github.com/nyaomaru/changelog-bot/pull/156)

**Full Changelog**: https://github.com/nyaomaru/changelog-bot/compare/v0...v0.6.4

[v0.6.4]: https://github.com/nyaomaru/changelog-bot/compare/v0.6.3...v0.6.4
Enter fullscreen mode Exit fullscreen mode