Semantic Version
Generator

Automatic semantic versioning based on git commit messages. Use as a CLI tool, GitHub Action, or Docker container.

Get Started View on GitHub
Version License Go Report
terminal 
$ semver-gen generate -l
SEMVER 1.5.2

$ semver-gen generate -r https://github.com/user/repo
SEMVER 2.3.0

Features

Automatic versioning that just works

Automatic Versioning

Calculates version based on commit message keywords

GitHub Action

Use directly in your CI/CD workflows

Docker Ready

Multi-arch Docker images for any environment

Configurable Keywords

Define your own trigger words for version bumps

Respects Tags

Optional mode to respect existing git tags

Release Candidates

Support for RC versions like 1.3.37-rc.1

Installation

Get started in seconds

Homebrew (macOS) 

brew install --cask lukaszraczylo/taps/semver-generator

Manual Download

Download from the releases page.

Supported: Darwin ARM64/AMD64, Linux ARM64/AMD64, Windows AMD64

Docker 

docker pull ghcr.io/lukaszraczylo/semver-generator:latest

Usage

Multiple ways to use semver-generator

CLI Usage 

# Local repository
semver-gen generate -l

# Remote repository
semver-gen generate -r https://github.com/user/repo

# With custom config
semver-gen generate -l -c semver.yaml

# Strict mode (only exact matches)
semver-gen generate -l -s

# Respect existing tags
semver-gen generate -l -e

# Self-update to latest version (no auth required)
semver-gen -u

Flags

  • -l, --local Use local repository
  • -r, --repository Remote repository URL
  • -c, --config Path to config file
  • -s, --strict Strict matching
  • -e, --existing Respect existing tags
  • -d, --debug Enable debug mode
  • -u, --update Self-update to latest version
  • -v, --version Display current version

GitHub Action 

jobs:
  version:
    runs-on: ubuntu-latest
    outputs:
      version: ${{ steps.semver.outputs.semantic_version }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: '0'

      - name: Generate version
        id: semver
        uses: lukaszraczylo/semver-generator@v1
        with:
          config_file: semver.yaml
          repository_local: true

      - name: Use version
        run: echo "Version: ${{ steps.semver.outputs.semantic_version }}"

How It Works

Version calculation based on commit messages

0.0.1 - PATCH - starting commit
0.0.2 - PATCH - another commit
0.0.4 - PATCH - commit with 'Update' => DOUBLE increment PATCH
0.1.0 - MINOR - commit with 'Change' => increment MINOR, reset PATCH
0.1.1 - PATCH - additional commit
1.0.1 - MAJOR - commit with 'BREAKING' => INCREMENT MAJOR, reset MINOR
1.0.2 - PATCH - another commit
MAJOR

Breaking changes

Keywords: "breaking"

MINOR

New features

Keywords: "change", "improve"

PATCH

Bug fixes

Keywords: "update", "initial"

Configuration

Customize keywords and behavior

semver.yaml

version: 1

# Starting version (optional)
force:
  major: 1
  minor: 0
  patch: 0
  commit: 69fbe2df696f40281b9104ff073d26186cde1024

# Commits to ignore
blacklist:
  - "Merge branch"
  - "Merge pull request"
  - "feature/"

# Keywords for version bumps
wording:
  patch:
    - update
    - initial
    - fix
  minor:
    - change
    - improve
    - add
  major:
    - breaking
  release:
    - release-candidate
    - add-rc