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

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

📦 Installation & Quickstart

1. Install from PyPI

pip install gitag

1. 🔍 Preview Next Tag (Dry-Run)

gitag --dry-run

1. 🚀 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

1. Analyze Commits 🔎 Reads your Git history since the last tag, matching commit messages against Conventional Commits patterns (e.g., feat:, fix:, perf:).
2. 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:"]

See the full Config Reference for advanced options.

🎉 Conclusion

By adopting gitag, you can:

• ❌ Eliminate manual errors in version bumps
• ⚡ Accelerate release cycles with automated tagging
• 📑 Maintain clear changelogs aligned with your commit history

Start today by running:

gitag --dry-run

and transform your release process with robust, semantic versioning automation.

Happy tagging! 🏷️