Semantic Release
Introduction
Semantic Release automates versioning and changelog generation by analyzing commit messages using Conventional Commits. Once a merge request is merged into master, the system evaluates commit history since the last release, determines the appropriate version bump, updates version metadata and changelogs, tags the release, and publishes updates—without manual intervention.
Release Rules
We’ve configured Semantic Release to watch for these commit types (as recognized by the CI):
- Breaking changes (
BREAKING CHANGE:in the body or a!in the header) → Major release (X.0.0) feat→ Minor release (0.X.0)fix,docs,refactor,style,build,ci,test,perf→ Patch release (0.0.X)
How You Should Format Your Merge Requests
When creating a merge request:
- Title must use a Conventional Commit prefix:
feat: add new metrics widget TICKET-123
- Indicate breaking changes (if needed):
- Using a
!in the header:feat!: redesign API interface TICKET-456 - Or including it in the footer of the commit body:
BREAKING CHANGE: old endpoint removed
- Using a
What Happens After Merge
Once your merge is added to master with a valid commit message:
- Semantic Release reads the commit(s),
- Determines type of bump (major/minor/patch),
- Generates a version tag and changelog update,
- Commits and pushes the changes automatically.
You'll see a new tag (like v1.2.3) created.
Prefix Reference
| Prefix | When to use | Release Type |
|---|---|---|
(prefix)!: | Breaking changes | Major |
feat: | New features or enhancements | Minor |
fix: | Bug fixes | Patch |
docs: | Documentation updates | Patch |
refactor: | Code refactors that don't change behavior | Patch |
style: | Visual/UI updates (no behavior changes) | Patch |
build: | Changes to build process, dependencies, or tools | Patch |
ci: | Continuous integration config updates (e.g., GitLab CI) | Patch |
test: | Adding or modifying tests | Patch |
perf: | Performance improvements that don’t change behavior | Patch |
chore: | Maintenance tasks that don’t affect user-facing behavior | Patch |
TL;DR
- Always use Conventional Commit prefixes in your MR titles or final squash commit message.
- Mark breaking changes clearly with
!orBREAKING CHANGE:. - Merge requests that include those prefixes will automatically trigger version bumps
- Missing or incorrect formatting may result in no release being created.