DEV Community

Kyle Y. Parsotan
Kyle Y. Parsotan

Posted on

Auto versioning + changelog generation using Github Action

#github #git #cicd #webdev

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
Enter fullscreen mode Exit fullscreen mode

🧠 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
Enter fullscreen mode Exit fullscreen mode

Breaking change (major version bump)

```bash id="c3"
feat!: redesign API structure




or



```bash id="c4"
BREAKING CHANGE: remove old auth system
Enter fullscreen mode Exit fullscreen mode

⚙️ 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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

🧠 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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

❌ 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
Enter fullscreen mode Exit fullscreen mode

Top comments (0)