Trunk Semver

Trunk-based semantic versioning for GitHub Actions. Automatic version bumps from branch naming patterns. Feature branches bump minor, fix branches bump patch.

Quick Start

name: Release
on:
  push:
    branches: [main]

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

      - uses: TheKathan/trunk-semver@v1
        with:
          major-version: "1"

That's it. When you merge a PR to main, it figures out the version bump from your branch name and tags it automatically.

How It Works

The action looks at your merged PR's source branch and bumps the version accordingly:

• feature/* or feat/* → bumps minor version (1.0.0 → 1.1.0)
• Everything else → bumps patch version (1.0.0 → 1.0.1)

It won't create duplicate tags if the commit already has one, and you can set your own major version.

Branch Patterns

Main Branch (default mode)

When a PR is merged to main:

Source Branch	Version Bump	Example
feature/*, feat/*	Minor (1.1.0 → 1.2.0)	v1.2.0
fix/*, hotfix/*, bugfix/*	Patch (1.1.0 → 1.1.1)	v1.1.1
chore/*	Patch (1.1.0 → 1.1.1)	v1.1.1
docs/*	Patch (1.1.0 → 1.1.1)	v1.1.1
refactor/*	Patch (1.1.0 → 1.1.1)	v1.1.1
perf/*, performance/*	Patch (1.1.0 → 1.1.1)	v1.1.1
test/*, tests/*	Patch (1.1.0 → 1.1.1)	v1.1.1
build/*	Patch (1.1.0 → 1.1.1)	v1.1.1
ci/*	Patch (1.1.0 → 1.1.1)	v1.1.1
style/*	Patch (1.1.0 → 1.1.1)	v1.1.1
Any other branch	Patch (1.1.0 → 1.1.1)	v1.1.1

Pre-release Mode (enable-prerelease: true)

Set enable-prerelease: "true" to version feature branches before they're merged:

- uses: TheKathan/trunk-semver@v1
  with:
    major-version: "1"
    enable-prerelease: "true"

This creates tags with suffixes:

Branch Pattern	Version Format	Example
feature/*, feat/*	v{major}.{minor}.{patch}-alpha.{n}	v1.2.0-alpha.1
fix/*, hotfix/*, bugfix/*	v{major}.{minor}.{patch}-fix.{n}	v1.1.1-fix.1
chore/*	v{major}.{minor}.{patch}-chore.{n}	v1.1.1-chore.1
docs/*	v{major}.{minor}.{patch}-docs.{n}	v1.1.1-docs.1
refactor/*	v{major}.{minor}.{patch}-refactor.{n}	v1.1.1-refactor.1
perf/*, performance/*	v{major}.{minor}.{patch}-perf.{n}	v1.1.1-perf.1
test/*, tests/*	v{major}.{minor}.{patch}-test.{n}	v1.1.1-test.1
build/*	v{major}.{minor}.{patch}-build.{n}	v1.1.1-build.1
ci/*	v{major}.{minor}.{patch}-ci.{n}	v1.1.1-ci.1
style/*	v{major}.{minor}.{patch}-style.{n}	v1.1.1-style.1

When you merge to main, it drops the suffix and creates the final version.

Inputs

Input	Default	Description
major-version	1	Major version number
enable-prerelease	false	Enable pre-release tags on feature branches
github-token	${{ github.token }}	Token for API access
branch-patterns	""	Custom branch patterns (JSON format, optional)
comment-on-pr	false	Add version comment to PRs (requires enable-prerelease: true)
add-to-summary	false	Add version to GitHub Actions job summary

Outputs

Output	Description
version	The version tag that was created (e.g., v1.2.3)
is-prerelease	true if it's a pre-release, false otherwise
branch	Branch name used for versioning
previous-version	Previous version tag
bump-type	Type of version bump (Minor or Patch)

PR Comments & Job Summaries

Enable helpful version information directly in your pull requests and workflow summaries:

- uses: TheKathan/trunk-semver@v1
  with:
    major-version: "1"
    enable-prerelease: "true"
    comment-on-pr: "true"      # Adds comment to PRs
    add-to-summary: "true"      # Adds to workflow summary

Both features display the same information in a clean table format:

## 📦 Version: v1.2.0-alpha.1

| Field | Value |
|-------|-------|
| Type | Pre-release |
| Branch | feature/new-feature |
| Bump | Minor |

Notes:

• PR comments only appear when enable-prerelease is true (versions are created on feature branches)
• Job summaries appear on main branch merges or when enable-prerelease is true
• PR comments are updated in place (no duplicate comments)

Creating Releases

If you want GitHub releases instead of just tags:

- name: Version
  id: version
  uses: TheKathan/trunk-semver@v1

- name: Create Release
  if: steps.version.outputs.is-prerelease == 'false'
  env:
    GH_TOKEN: ${{ github.token }}
  run: gh release create ${{ steps.version.outputs.version }} --generate-notes

FAQ

How do I change the major version?

Use the major-version input to set your desired major version:

- uses: TheKathan/trunk-semver@v1
  with:
    major-version: "2"  # Creates v2.x.x tags

When you're ready to bump to a new major version (e.g., v1 → v2), simply update this value. The action will start creating tags from the new major version baseline (e.g., v2.0.0, v2.0.1, etc.).

Can I customize branch patterns?

Yes! Use the branch-patterns input with JSON format:

- uses: TheKathan/trunk-semver@v1
  with:
    branch-patterns: |
      {
        "minor": ["feature/*", "feat/*", "enhancement/*"],
        "patch": ["fix/*", "hotfix/*", "bugfix/*", "chore/*"]
      }

Default patterns (if not specified):

• Minor bump: feature/*, feat/*
• Patch bump: fix/*, hotfix/*, bugfix/*, chore/*, docs/*, refactor/*, perf/*, test/*, build/*, ci/*, style/*

What happens if I don't use conventional branch names?

On main branch: Any branch name defaults to a patch bump (e.g., v1.0.0 → v1.0.1)

With enable-prerelease: true: The action will fail with an error message if your branch doesn't match any expected patterns. This ensures intentional versioning.

Solution: Either:

1. Rename your branch to match a pattern (e.g., feature/my-feature)
2. Add custom patterns using branch-patterns to include your naming convention
3. Set enable-prerelease: false and only version on main branch merges

License

GPL-3.0

Contributing

Found a bug or have an idea? Open an issue or submit a PR at TheKathan/trunk-semver