semrel

semrel

A semantic versioning and release automation tool, based on conventional commits.

Features

• Automatic version calculation based on conventional commit messages
• Support for GitHub and GitLab releases
• Configurable commit type mappings
• Release notes generation with filtering and regex transformations
• Development mode for pre-1.0.0 projects
• GitHub Actions integration
• JSON output for CI/CD pipelines

Installation

Homebrew

brew install greatliontech/tap/semrel

Go Install

go install github.com/greatliontech/semrel@latest

Binary Downloads

Download pre-built binaries from the releases page.

Quick Start

# Show the next version based on commits
semrel

# Show the current version
semrel current

# Create a release on GitHub/GitLab
semrel release

# Validate a version string
semrel validate 1.2.3

# Compare versions
semrel compare --ge 1.0.0

Commands

Default Command

Calculate and display the next semantic version based on conventional commits since the last tag.

semrel [flags]

Flags:
  -p, --prerelease string    Add prerelease suffix (e.g., alpha.1)
  -b, --build string         Add build metadata
      --create-tag           Create the git tag
      --push-tag             Push the tag to remote
      --current-branch-only  Only consider tags from current branch
      --auth-username        Username for basic auth
      --auth-password        Password for basic auth
      --auth-token           Token for auth
  -v, --verbose              Enable verbose output
      --dry-run              Simulate actions without making changes

current

Print the current (latest) release version.

semrel current [flags]

Flags:
      --current-branch-only  Only consider tags from current branch
      --json                 Output in JSON format

release

Create a release on GitHub or GitLab with generated release notes.

semrel release [flags]

Flags:
  -p, --prerelease string    Add prerelease suffix
  -b, --build string         Add build metadata
      --current-branch-only  Only consider tags from current branch
      --json                 Output in JSON format

compare

Compare the current or supplied version against constraints.

semrel compare [version] [flags]

Flags:
      --le strings           Less than or equal to
      --ge strings           Greater than or equal to
      --lt strings           Less than
      --gt strings           Greater than
      --current-branch-only  Only compare the current branch
      --json                 Output in JSON format

validate

Validate a semantic version string.

semrel validate <version> [flags]

Flags:
      --strict         Strict semver validation
      --noPrerelease   Do not allow pre-release versions
      --noBuild        Do not allow build metadata
      --json           Output in JSON format

Configuration

Create a .semrel.yaml file in your repository root:

# Commit types that trigger a patch version bump
patchTypes:
  - fix
  - chore
  - perf

# Commit types that trigger a minor version bump
minorTypes:
  - feat

# Commit types that trigger a major version bump
majorTypes:
  - breaking

# Default bump when no commits match types (none, patch, minor, major)
defaultBump: none

# Initial version for new repositories
initialVersion: 1.0.0

# Development mode: starts at 0.1.0, breaking changes are minor bumps
development: false

# Version prefix (e.g., "v" for v1.0.0)
prefix: "v"

# Automatically create git tag
createTag: false

# Automatically push tag to remote
pushTag: false

# Platform for releases (github, gitlab)
platform: github

# Filters for release notes
filters:
  types:
    - docs
    - test
  scopes:
    - internal

# Regex rules for transforming commit messages in release notes
matchRules:
  - match: "TRACK-(\\d+)"
    replace: "[#$1](https://tracker.example.com/TRACK-$1)"

Conventional Commits

semrel parses commit messages following the Conventional Commits specification:

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Breaking Changes

Breaking changes can be indicated in two ways:

1. Attention marker - Add ! after the type/scope:

   feat!: remove deprecated API
   feat(api)!: change response format
   

2. Footer - Add BREAKING CHANGE: in the commit body:

   feat: update authentication
   
   BREAKING CHANGE: JWT tokens now expire after 1 hour
   

Version Bumps

Development Mode

When development: true is set:

• Initial version starts at 0.1.0 instead of 1.0.0
• Breaking changes on 0.x.x versions bump the patch version instead of major
• Once you reach 1.0.0, breaking changes behave normally

Environment Variables

GitHub Actions

semrel can be used as a GitHub Action:

name: Release

on:
  push:
    branches: [main]

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
        with:
          fetch-depth: 0

      - uses: greatliontech/semrel@main
        id: semrel
        with:
          releaseToken: ${{ secrets.RELEASE_TOKEN }}
          release: true

      - run: echo "Next version is ${{ steps.semrel.outputs.next-version }}"

Action Inputs

Action Outputs

Exit Codes

JSON Output

All commands support --json flag for machine-readable output:

# Current version
semrel current --json
# {"version":"1.2.3","tag":"v1.2.3"}

# Validate
semrel validate 1.2.3 --json
# {"input":"1.2.3","valid":true,"version":"1.2.3"}

# Compare
semrel compare --ge 1.0.0 --json
# {"version":"1.2.3","result":true}

# Release
semrel release --json
# {"current":"v1.2.3","next":"v1.3.0","created":true}

License

Apache License 2.0 - see LICENSE for details.