Auto versioning + changelog generation is a very real production pattern used in open-source and SaaS teams to avoid messy release notes and manual tagging.
We’ll build a clean system using:
- 🧠 Conventional commits (rules for commit messages)
- 🤖 Semantic versioning automation
- 📜 Auto-generated CHANGELOG
- 🚀 GitHub Actions workflow
🧠 0. What we’re building
```plaintext id="flow0"
commit → push → GitHub Action
↓
analyze commits
↓
bump version (patch/minor/major)
↓
generate changelog
↓
create git tag
↓
create GitHub release
---
# 📦 1. Install required tool (standard approach)
We’ll use:
👉 **semantic-release** (industry standard)
```bash id="inst1"
npm install --save-dev semantic-release @semantic-release/changelog @semantic-release/git @semantic-release/github
🧠 2. Use Conventional Commits (VERY important)
Your commits MUST follow this format:
✅ Examples
Feature (minor version bump)
```bash id="c1"
feat: add user login system
### Fix (patch version bump)
```bash id="c2"
fix: resolve navbar bug on mobile
Breaking change (major version bump)
```bash id="c3"
feat!: redesign API structure
or
```bash id="c4"
BREAKING CHANGE: remove old auth system
⚙️ 3. Create semantic-release config
📁 .releaserc.json
```json id="r1"
{
"branches": ["main"],
"plugins": [
"@semantic-release/commit-analyzer",
"@semantic-release/release-notes-generator",
"@semantic-release/changelog",
"@semantic-release/github",
[
"@semantic-release/git",
{
"assets": ["package.json", "CHANGELOG.md"],
"message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
}
]
]
}
---
# 📜 4. Create CHANGELOG file
```bash id="ch1"
touch CHANGELOG.md
Start empty:
```md id="ch2"
Changelog
All notable changes will be documented here.
---
# 🚀 5. GitHub Actions workflow (AUTO VERSION + CHANGELOG)
## 📁 `.github/workflows/release.yml`
```yaml id="w1"
name: Auto Version & Changelog
on:
push:
branches:
- main
jobs:
release:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Setup Node
uses: actions/setup-node@v4
with:
node-version: 20
- name: Install dependencies
run: npm install
- name: Run semantic release
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: npx semantic-release
🧠 6. What this does automatically
When you push to main:
It will:
- Analyze commits
-
Decide version bump:
- fix → 1.0.1
- feat → 1.1.0
- breaking → 2.0.0
Generate changelog
Create Git tag
Create GitHub Release
Update
CHANGELOG.md
📜 7. Example auto-generated changelog
```md id="log1"
1.2.0 (2026-05-23)
Features
- add user authentication system
- add dashboard analytics
Bug Fixes
- fix navbar alignment on mobile
- fix API timeout issue ```
🏷️ 8. Example GitHub releases
GitHub will automatically create:
```plaintext id="rel1"
v1.2.0 - Production Release
Features:
- user auth system
- analytics dashboard
Fixes:
- mobile navbar bug ```
🔐 9. GitHub Secrets needed
Make sure this exists:
```plaintext id="sec1"
GITHUB_TOKEN (auto provided by GitHub Actions)
No extra setup required.
---
# 🧪 10. Real workflow in action
### Developer flow:
```plaintext id="flow1"
git commit -m "feat: add dashboard UI"
git push origin main
GitHub automatically:
- Detects commit type (
feat) - Bumps version → minor update
- Updates CHANGELOG.md
- Creates git tag (v1.3.0)
- Publishes GitHub release
🔥 11. Pro upgrades (used in companies)
🟢 Auto publish npm package
```yaml id="npm1"
- run: npm publish ```
🟡 Slack release notification
```yaml id="slack1"
- name: Notify Slack run: curl -X POST $SLACK_WEBHOOK ```
🔵 Multi-branch releases
```json id="branch1"
"branches": ["main", "next"]
---
## 🟣 Changelog formatting customization
You can group commits like:
* Features
* Fixes
* Performance
* Breaking changes
---
# ⚠️ 12. Common mistakes
### ❌ Not using conventional commits
→ versioning won’t work properly
### ❌ Pushing messy commit messages
```bash id="bad1"
fix stuff
update
❌ Forgetting fetch-depth: 0
→ release history breaks
🧠 Final architecture
```plaintext id="final1"
Commit (feat/fix/breaking)
↓
GitHub Action triggers
↓
semantic-release analyzes commits
↓
bumps version automatically
↓
updates CHANGELOG.md
↓
creates git tag + GitHub release
---
# 🚀 What you just built (REAL DEVOPS LEVEL)
You now have:
* 🤖 Automated versioning
* 📜 Auto changelog generation
* 🏷️ Git tags + GitHub releases
* 🚀 CI/CD-ready release pipeline