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 (0)