🚀 Automate Your Releases with gitag: The Ultimate CLI for Semantic Versioning

#webdev #devops #git #opensource

In today’s fast-paced development environments, manually maintaining version numbers and generating changelogs can become a bottleneck. gitag is a modern, lightweight CLI tool designed to integrate seamlessly into your CI/CD pipeline, parsing Conventional Commits and applying Semantic Versioning automatically. Read on to learn how gitag can save you time ⏱️, reduce human error ❌, and improve release consistency 🔄.

🤔 Why You Need Automatic Versioning

Maintaining consistent version numbers and comprehensive changelogs is challenging:

Human Error ❌: Manual bumps can be forgotten or inconsistent, leading to mismatched tags.
Inefficient Workflows 🐢: Time spent on versioning and changelog updates diverts focus from actual development.
Poor Traceability 🔍: Without clear semantic tags, it’s hard to understand which commits introduced features, fixes, or breaking changes.

By automating this process, gitag ensures:

🔑 Reliable Tags: Always follow Semantic Versioning (MAJOR.MINOR.PATCH).
📄 Consistent Changelogs: Automatically generate or update your CHANGELOG.md.
🤖 Seamless CI/CD Integration: No manual steps—just push and let gitag handle the rest.

✨ Key Features of gitag

Feature	Benefit
✅ Conventional Commits parsing	Detects `feat:`, `fix:`, `BREAKING CHANGE:`, and more
🔢 Semantic Versioning support	Automatic MAJOR, MINOR, PATCH bumps
🏁 Dry-Run & CI Modes	Preview changes before applying; perfect for pipelines
📝 Changelog Generation (BETA)	Keeps your `CHANGELOG.md` in sync with commits
⚙️ Configurable via `pyproject.toml`	Customize prefixes, merge strategies, and bump keywords
🔀 Merge Commit Strategies	Choose auto, always, or merge-only bump behavior
🤝 GitHub Actions Example	Out-of-the-box workflow provided for quick setup
🧪 100% Tested with pytest	Confidence in production usage

📦 Installation & Quickstart

Install from PyPI

   pip install gitag

🔍 Preview Next Tag (Dry-Run)

   gitag --dry-run

🚀 Tag & Changelog in CI

   gitag --ci --changelog

For development or contributions:

git clone https://github.com/henrymanke/gitag.git
cd gitag
pip install -e .[dev]

🔧 How gitag Works

Analyze Commits 🔎 Reads your Git history since the last tag, matching commit messages against Conventional Commits patterns (e.g., feat:, fix:, perf:).
Determine Bump Level 📈

Major 🔥: BREAKING CHANGE:, !:
Minor ✨: feat: or feature(...)
Patch 🐛: fix:, perf:, docs:, chore:, etc.
1. Generate Tag & Changelog 🏷️ Applies the next semantic version tag (e.g., v1.2.3 → v1.3.0), optionally updates CHANGELOG.md, and—if in CI mode—pushes tags to remote.

🤖 Integrating with GitHub Actions

Add the following workflow to .github/workflows/auto-tag.yml to automate tagging on every push to main:

name: Auto Tag

on:
  push:
    branches: [main]

jobs:
  tag:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    env:
      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    steps:
      - name: 📥 Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: 🐍 Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - name: 📦 Install gitag
        run: pip install gitag
      - name: 🚀 Run gitag (CI + Changelog)
        run: gitag --ci --debug --changelog
      - name: 📤 Upload CHANGELOG
        uses: actions/upload-artifact@v4
        with:
          name: changelog
          path: CHANGELOG.md

⚙️ Configuration Example

Customize gitag behavior via pyproject.toml:

[tool.gitag]
prefix = "v"
merge_strategy = "auto"

[tool.gitag.bump_keywords]
major = ["BREAKING CHANGE", "!:"]
minor = ["feat:"]
patch = ["fix:", "perf:", "docs:", "chore:"]