semrel

Status: alpha (v0.3.x) — core pipeline, plugin system, and CI/CD are fully functional. Self-versioned via semrel. Not yet recommended for production use; see ROADMAP.md for the path to v1.0.0.

A Go-based semantic versioning and release system with a plugin architecture that automates the full release lifecycle. Designed for monorepos and multi-language projects.

Features

• 🔍 Conventional Commits parser with configurable bump rules
• 🔌 Rich ecosystem of standalone plugins for providers, package updaters, and hooks
• 📝 Multi-format changelog — Markdown (Keep a Changelog), per-package monorepo changelogs
• 🏗️ Monorepo support — independent/lockstep versioning, package discovery, dependency graph, per-package changelogs
• 🔐 Supply-chain security — Cosign signing, CycloneDX/SPDX SBOM, SLSA Level 1 provenance
• ⚙️ GitHub Actions native integration
• 🧩 Plugin runtime — subprocess-based plugin execution from ~/.semrel/plugins/ or $PATH
• 🔗 Issue tracking — Jira and GitHub issue reference extraction from commit messages
• 📊 Release analytics — append-only NDJSON release history tracking
• ✅ commitlint — validate commit messages from CLI, git range, or stdin

Installation

go install github.com/GoSemantics/semrel/cmd/semrel@latest
semrel --version

Install any plugins you want to use:

semrel plugin install github
semrel plugin install npm

Quick Start

# Validate commit messages
semrel lint

# Dry-run release (preview what would happen)
semrel release --dry-run

# Run the full release pipeline
semrel release

Available Plugins

Install any plugin with semrel plugin install <name>.

Plugin	Type	Description	Repo
Conditions
github-actions	Condition	Allow releases only on GitHub Actions CI	SemRels/condition-github-actions
gitlab-ci	Condition	Allow releases only on GitLab CI	SemRels/condition-gitlab-ci
gitea-actions	Condition	Allow releases only on Gitea Actions	SemRels/condition-gitea-actions
generic	Condition	Generic CI environment condition	SemRels/condition-generic
Analyzers
conventional	Analyzer	Conventional Commits commit analyzer	SemRels/analyzer-conventional
default	Analyzer	Default commit analyzer	SemRels/analyzer-default
Generators
changelog-md	Generator	Markdown changelog (Keep a Changelog format)	SemRels/generator-changelog-md
changelog-html	Generator	HTML changelog generator	SemRels/generator-changelog-html
release-notes	Generator	Release notes generator	SemRels/generator-release-notes
Providers
github	Provider	GitHub releases, assets, and tags	SemRels/provider-github
gitlab	Provider	GitLab releases and tags	SemRels/provider-gitlab
gitea	Provider	Gitea releases and tags	SemRels/provider-gitea
bitbucket	Provider	Bitbucket releases and tags	SemRels/provider-bitbucket
git	Provider	Local git tag only (no platform integration)	SemRels/provider-git
Updaters
npm	Updater	Bump package.json version	SemRels/updater-npm
docker	Updater	Build and push Docker images	SemRels/updater-docker
helm	Updater	Bump Helm chart version	SemRels/updater-helm
cargo	Updater	Publish Rust/Cargo crate	SemRels/updater-cargo
python	Updater	Bump PyPI package version	SemRels/updater-python
gradle	Updater	Bump Gradle version	SemRels/updater-gradle
maven	Updater	Publish Maven artifact	SemRels/updater-maven
nuget	Updater	Bump NuGet package version	SemRels/updater-nuget
gobinary	Updater	Update Go version variable in source	SemRels/updater-go
homebrew	Updater	Update Homebrew formula	SemRels/updater-homebrew
terraform	Updater	Bump Terraform module version	SemRels/updater-terraform
Hooks
slack	Hook	Send release notifications to Slack	SemRels/hook-slack
teams	Hook	Send release notifications to Microsoft Teams	SemRels/hook-teams
matrix	Hook	Send release notifications to Matrix/Element	SemRels/hook-matrix
email	Hook	Send release notification emails	SemRels/hook-email
jira	Hook	Transition Jira issues on release	SemRels/hook-jira
gitplugin	Hook	Run arbitrary git operations post-release	SemRels/hook-gitplugin

Configuration

Copy .semrel.yaml.example to .semrel.yaml and adjust it for your project. Plugin entries now refer to standalone binaries, for example:

plugins:
  - uses: github
  - uses: npm
  - uses: docker
    args:
      image: myorg/myapp

See docs/config-reference.md for all options.

Architecture

• Core engine: Conventional Commits analysis, SemVer calculation, changelog generation, git tag creation
• Plugin system: pkg/plugininstance.Orchestrator launches standalone plugin binaries in subprocesses
• Plugin discovery: ~/.semrel/plugins/semrel-plugin-<name> first, then $PATH

See docs/architecture.md for the full design.

Documentation

• Architecture Overview — pipeline design and component overview
• Configuration Reference — all .semrel.yaml options
• Plugin Development Guide — build standalone plugins
• CNCF Due Diligence — project overview for CNCF Sandbox application
• ADRs — architectural decision records
• ROADMAP — public project roadmap

Supply Chain Security

semrel takes supply-chain security seriously:

• Signed releases: Artifacts signed with Sigstore Cosign (keyless OIDC)
• SBOM: CycloneDX 1.4 and SPDX 2.3 Bills of Materials published per release
• SLSA provenance: Level 1 build provenance documenting artifact digests
• DCO: Developer Certificate of Origin required on all commits
• REUSE/SPDX: License compliance enforced in CI on every PR

See SECURITY.md for vulnerability reporting and artifact verification instructions.

Contributing

See CONTRIBUTING.md. All contributions require:

• DCO sign-off (git commit -s)
• Conventional Commits
• REUSE/SPDX compliance

Security

Please report vulnerabilities via GitHub Security Advisories. See SECURITY.md for the full policy.

License

Apache 2.0 — see LICENSE.

Copyright 2026 The semrel Authors.