changelog-ci

Auto-generate CHANGELOG.md from merged PRs and git history.

Features

• 🚀 Automatic changelog generation from git commits and GitHub PRs
• 📋 Conventional commit parsing (feat, fix, docs, perf, chore, etc.)
• 🏷️ Breaking change detection from ! suffix and BREAKING CHANGE footers
• 📝 Keep-a-Changelog format with markdown and JSON output
• 🔧 Configurable via .changelog-ci.yaml
• 🏃 Dry-run mode for preview
• 🏷️ Release management — generate, commit, and tag in one command
• 👥 Contributor listing
• 🌐 GitHub API integration for merged PRs
• 📦 Local mode — works without API access

Install

pip install changelog-ci

Usage

# Generate from local git history
changelog-ci generate

# Since a specific tag
changelog-ci generate --since v2.1.0

# Preview without writing
changelog-ci generate --dry-run

# JSON output
changelog-ci generate --format json

# From GitHub PRs
changelog-ci generate --owner myorg --repo-name myrepo

# Create initial CHANGELOG.md
changelog-ci init

# Validate changelog is up to date
changelog-ci validate

# Create a release (generate + commit + tag)
changelog-ci release 2.2.0

# List contributors
changelog-ci contributors

Configuration

Create .changelog-ci.yaml in your repo root:

categories:
  - name: Features
    labels: [enhancement, feature]
    prefixes: [feat]
  - name: Bug Fixes
    labels: [bug, bugfix]
    prefixes: [fix]
header: "# Changelog"
template: keepachangelog
unreleased: true
tag_prefix: "v"
ignore_labels: [skip-changelog, dependencies]
contributors: true

Conventional Commits

changelog-ci understands conventional commit format:

feat: add login page
fix(auth): resolve token expiry (#42)
feat(api)!: change response format
docs: update API reference
perf(db): optimize query performance

Breaking changes are detected from:

• ! after the type/scope: feat!: redesign API
• BREAKING CHANGE: footer in commit body

Output Format

# Changelog

## [2.2.0] - 2026-04-07

### Features
- Add pagination support (#142) — @johndoe

### Bug Fixes
- Fix race condition in file writes (#145) — @janedoe

### ⚠️ Breaking Changes
- Rename User.getClient() to User.getActiveClient() (#143)

Development

pip install -e ".[dev]"
pytest

License

MIT © Hiren Thakore