Introduction
semantic-release removes the human decision-making from version numbering and package publishing. It reads your Git commit history, determines the next semantic version based on the Conventional Commits specification, generates release notes, and publishes the package to npm or other registries. The entire process runs in CI with zero manual steps.
What semantic-release Does
- Analyzes commit messages since the last release to calculate the next semver version automatically
- Generates and updates CHANGELOG files from structured commit history
- Publishes packages to npm, GitHub Packages, or other registries as part of CI
- Creates Git tags and GitHub/GitLab releases with generated release notes
- Supports plugins for custom release steps like Docker image publishing or Slack notifications
Architecture Overview
semantic-release runs as a Node.js CLI that executes a pipeline of lifecycle steps: verify conditions, analyze commits, verify release, generate notes, prepare, publish, and notify. Each step is handled by configurable plugins. The commit analyzer plugin parses commits following the Conventional Commits format (feat, fix, breaking change) to determine whether the release is a patch, minor, or major bump. Configuration lives in .releaserc, release.config.js, or package.json.
Self-Hosting & Configuration
- Install with
npm install --save-dev semantic-releasein your project - Create a
.releaserc.jsonfile to configure branches, plugins, and publish targets - Set up CI environment variables for npm tokens (
NPM_TOKEN) and Git credentials (GITHUB_TOKEN) - Configure branch rules to support pre-releases from
betaornextbranches - Add or remove plugins to customize the release pipeline for your workflow
Key Features
- Enforces semantic versioning strictly through commit message analysis
- Multi-branch release support for stable, pre-release, and maintenance channels
- Extensible plugin architecture with official plugins for npm, GitHub, GitLab, and more
- Dry-run mode previews what the next release would look like without publishing
- Works with any CI provider including GitHub Actions, GitLab CI, CircleCI, and Jenkins
Comparison with Similar Tools
- Changesets — Requires developers to manually write changeset files; semantic-release is fully automatic from commits
- release-please — Google's release automation tool; uses pull requests for releases instead of direct publishing
- standard-version — Generates changelogs and bumps versions without publishing; now deprecated in favor of semantic-release
- Lerna — Manages monorepo versioning and publishing; semantic-release focuses on single-package automated releases
- GoReleaser — Release automation for Go binaries; semantic-release targets the npm/Node.js ecosystem primarily
FAQ
Q: Does semantic-release work with monorepos?
A: The core tool targets single packages. For monorepos, use the semantic-release-monorepo plugin or consider Changesets or Lerna.
Q: What commit format does it require?
A: It uses the Conventional Commits specification by default: feat: for minor, fix: for patch, and BREAKING CHANGE: for major bumps.
Q: Can I use it outside the Node.js ecosystem? A: Yes. While it runs on Node.js, plugins exist for publishing Docker images, Helm charts, Python packages, and more.
Q: What happens if no releasable commits are found? A: semantic-release skips the release entirely and exits cleanly. No version bump or publish occurs.