# semantic-release: automated versioning and publishing from commit messages

> semantic-release derives the next version number, the changelog and the publish step from Angular-style commit messages on your release branch. It is a good fit for teams already running CI on npm packages, and a poor fit for anyone who wants to tag releases by hand.

**semantic-release/semantic-release** — Fully automated version management and package publishing. semantic-release Fully automated version management and package publishing semantic-release** automates the whole package release workflow including: determining the next version number, generating the release notes, and publishing the package.

- Repository: https://github.com/semantic-release/semantic-release
- Website: https://semantic-release.org
- Stars: 24,068 · Forks: 1,809
- Language: JavaScript
- License: MIT
- Published: 2026-08-04 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/semantic-release-semantic-release

## What semantic-release actually replaces

The manual release ritual has four steps: decide the version number, write the changelog, tag the commit, publish the artifact. semantic-release takes all four. The README describes it as automating "the whole package release workflow including: determining the next version number, generating the release notes, and publishing the package." The decision it removes is the human one. Version numbers come from commit messages rather than from a maintainer's judgement about how big a change felt.

That is the whole pitch, and it is narrower than it sounds. The project is not a changelog generator that happens to publish, and not a publisher that happens to tag. It is a pipeline that reads git history after a successful build and derives everything downstream from it. If your team already trusts its own judgement about when to cut a release, semantic-release is solving a problem you do not have. If your team ships small changes often and the bottleneck is the ceremony around each one, it fits.

## Commit messages are the version input

By default semantic-release uses Angular Commit Message Conventions. The README gives the mapping directly. A commit typed `fix(pencil): stop graphite breaking when too much pressure applied` produces a patch release. `feat(pencil): add 'graphiteWidth' option` produces a minor release. A commit containing the token `BREAKING CHANGE: ` in its footer produces a major release. The README notes that token must be in the footer, not the subject line, which is the single most common way people get an unexpected version.

The convention is configurable. The README points at the `preset` and `config` options of @semantic-release/commit-analyzer and @semantic-release/release-notes-generator, so a team that already uses a different convention can swap the parser rather than retrain everyone. The project also suggests commitizen or commitlint to help contributors produce valid messages and to enforce the format.

The design consequence is worth stating plainly. Your commit log becomes a public API. A contributor who writes `feat:` when they meant `fix:` will ship a minor version to every consumer, and there is no review step between that commit and the published package. The tool removes human judgement from versioning, which is the point, and also removes the human check that would have caught a mislabelled commit.

## The release pipeline: verify, analyze, generate, publish

semantic-release is meant to run on CI after a successful build on a release branch such as `master`, `main`, `next` or `beta`. Each push or merged pull request triggers a build, and the build runs the `semantic-release` command. The command walks a fixed sequence of steps, starting with Verify Conditions, which checks that everything needed to proceed is present before anything is changed.

The dependency list in package.json shows what ships by default: @semantic-release/commit-analyzer, @semantic-release/release-notes-generator, @semantic-release/npm and @semantic-release/github. Those four are the default plugin set, which is why a bare npm package on GitHub needs almost no configuration. Everything else, including the changelog file, comes from additional plugins such as @semantic-release/changelog and @semantic-release/git.

Plugins are the extension point for other ecosystems. The README states that any package managers and languages are supported via plugins, and that configuration can be shared through shareable configurations. That is how a Python project or a GitLab-hosted project gets covered: not by a flag, but by a plugin that knows how to publish there. The core does not know what npm is.

## Installing it and getting one real release out

The repository exposes the CLI as `semantic-release` through the `bin` field in package.json, which points at `bin/semantic-release.js`. The README's own install path is the npm package, so the dependency is added to a project like any other development tool.

```bash
npm install semantic-release
```

Configuration is read from a config file. The README documents the `branches` option for naming the release branches, and the default plugins need nothing beyond that.

```json
{
  "branches": ["main"]
}
```

Before wiring it into CI, run it on the release branch with full git history available. The README documents running the `semantic-release` command after a successful build on the release branch, and the CLI is what you invoke locally to see the computed result first.

```bash
npx semantic-release
```

What you should see is the current version, the version it intends to publish, and the release notes it would generate. If it reports that no release is needed, check that your commits since the last tag actually match the Angular convention; a commit like `updated stuff` is invisible to the analyzer. Once the local run matches your expectation, move the same command into the CI job that runs after tests on the release branch, and give that job a token with permission to publish to your registry and to create the GitHub release. The README links to CI configuration recipes at semantic-release.org for the specific CI systems it covers.

## Where the model breaks down

The failure mode that matters most is silent. If no commit since the last release matches the convention, semantic-release does not publish, and it does not necessarily make that loud. A team that merges a sequence of loosely worded commits will see the pipeline pass and no release appear, then spend time debugging the CI job rather than the commit log. A local run on the release branch is the diagnostic, and it is worth doing before assuming the CI configuration is at fault.

The second constraint is history. The analyzer reads git history to find the last release and the commits since then, so a shallow clone can leave it without the tags and commits it needs. The README does not document a rollback path for a release that was published with the wrong version; once the artifact is on the registry and the tag exists, undoing it is a manual operation outside the tool. That asymmetry is inherent to automation that publishes on every qualifying push.

Third, the default plugin set is npm and GitHub. A project publishing to a private registry, an internal artifact store, or a language ecosystem without a maintained plugin is looking at writing a plugin, not at a configuration change. The README is explicit that other package managers are supported via plugins, which is a statement about the architecture rather than a promise that a plugin exists.

## semantic-release compared with release-please and changesets

release-please takes the opposite approach to the same input. It also reads conventional commits, but instead of publishing directly it opens a pull request that proposes the version bump and the changelog. A human merges that pull request, and the merge is what triggers the release. The practical difference is where the review happens: semantic-release puts the review at the commit, release-please puts it at the release. Teams that want a person to see the version number before it ships should prefer release-please, and teams that consider that a bottleneck should prefer semantic-release.

changesets is built for monorepos and takes a third position. Contributors add a small markdown file describing the change and the bump type alongside their code, so the version intent is declared explicitly rather than inferred from the commit subject. That is more work per change and considerably more control over how several packages version together. A single-package repository gains little from it; a workspace with interdependent packages gains a lot.

The common thread is that all three need conventional or structured input. None of them will produce a sensible version from an unstructured commit log, so the choice is really about where in the workflow you want to insert the structure.

## Maintenance, licence and the upgrade cost

The repository is not archived, and the last push was on 2026-08-07. The most recent published version at that point was v26.0.0-beta.1, with v25.0.9 on 2026-08-05 as the latest stable release. A beta on the default branch alongside a stable line is normal for this project and is not a sign of abandonment.

The licence is MIT, which places few restrictions on commercial use, modification or redistribution. That is a statement about the licence text, not legal advice; if you redistribute semantic-release inside a product, read the LICENSE file in the repository rather than this paragraph.

The upgrade cost is concentrated in the plugin versions, not the core. package.json pins @semantic-release/commit-analyzer, @semantic-release/release-notes-generator, @semantic-release/npm and @semantic-release/github as separate dependencies, each with its own major version line. A major bump in the core often arrives with matching major bumps in those plugins, and each plugin can change its own options independently. Before upgrading, read the release notes for the core and for every plugin you have installed, and run the command on a branch that has commits of each type so you can see the computed version before it reaches the registry.

## Conclusion

Adopt semantic-release if your release branch already builds in CI, your contributors can be held to a commit convention, and your publish target has an official plugin such as @semantic-release/npm or @semantic-release/github. Do not adopt it for a repository where releases are decoupled from commits, where a human must approve each version number, or where the artifact has no plugin and no one is willing to write one. Before the first live run, verify three things yourself: that the CI job checks out full history, that a dry run on the real branch reports the version you expect, and that your CI token has the publish scope the plugin needs. If the dry run reports no release when you expected one, the cause is almost always a commit that does not match the default Angular preset.

## FAQ

### What does semantic-release mean?

It means the version number is derived from the meaning of your commits rather than chosen by a person. semantic-release reads commit messages, applies Semantic Versioning, and publishes without manual intervention.

### How do I set up semantic-release?

Install it with npm install semantic-release, add a configuration file naming your release branch, then run npx semantic-release on that branch to see the version it would compute before wiring the command into your CI job.

### What is the key difference between release-please and semantic-release?

release-please opens a pull request proposing the version and changelog and releases when a human merges it. semantic-release publishes directly from CI once commits land on the release branch, with no approval step in between.

### What is the difference between semantic releases and Conventional Commits?

Conventional Commits is the message format; semantic-release is the tool that consumes it. The README states semantic-release uses Angular Commit Message Conventions by default, and the format can be changed with the preset or config options of the commit-analyzer and release-notes-generator plugins.

### What is npx semantic release?

It runs the CLI that the package exposes through its bin field without a global install. The README documents running the semantic-release command on CI after a successful build.

## Sources

- [Official documentation](https://semantic-release.org)
- [Official README](https://github.com/semantic-release/semantic-release#readme)
- [Project repository](https://github.com/semantic-release/semantic-release)
- [Release notes](https://github.com/semantic-release/semantic-release/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/semantic-release-semantic-release