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:

1. Detects commit type (feat)
2. Bumps version → minor update
3. Updates CHANGELOG.md
4. Creates git tag (v1.3.0)
5. 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