How to use semantic-release: setup, commits and automated releases

What semantic-release needs before you start

The README lists Node.js, npm and Git as prerequisites. The tool is meant to run inside CI after each build, so you need a CI service already set up for your project.

Install method: package manager. The README's install command shown in the source is a clone of the repository: git clone https://github.com/semantic-release/semantic-release.git. For normal use, follow the project's documentation at semantic-release.org for installation and configuration.

• Node.js
• npm
• Git
• A CI service that runs your build on the release branch

Write commit messages in the Angular format

semantic-release decides the release type from your commit messages. By default it uses the Angular Commit Message Conventions. A fix produces a patch release, a feat produces a minor release, and a commit with a BREAKING CHANGE footer produces a major release.

The BREAKING CHANGE token must be in the footer of the commit. Tools such as commitizen or commitlint can help contributors write valid messages. The format can be changed with the preset or config options of the commit analyzer and release notes generator plugins.

• fix(scope): message gives a Fix Release (patch)
• feat(scope): message gives a Feature Release (minor)
• A commit with BREAKING CHANGE: in the footer gives a Breaking Release (major)

Run semantic-release in CI after each build

semantic-release is meant to run on the CI environment after every successful build on the release branch. Release branches include examples such as master, main, next and beta.

Each new commit pushed to a release branch, or merged from a pull request or another branch, triggers a CI build. That build runs the semantic-release command and makes a release only if there are changes since the last release that affect the package functionality.

• Pushes or merges to a release branch trigger a CI build
• The semantic-release command runs after the tests pass
• No release is made if nothing affects the package functionality

Understand the release steps

When you run semantic-release after the tests, it works through a fixed set of steps. Knowing them helps when a run fails, because the error tells you which step stopped.

• Verify Conditions: checks that everything needed to release is in place
• Get last release: finds the last release commit from Git tags
• Analyze commits: decides the release type from commits since then
• Verify release: checks the release is valid
• Generate notes: writes release notes for the new commits
• Create Git tag: tags the commit with the new version
• Prepare: prepares the release
• Publish: publishes the release
• Notify: announces the release or reports errors

Use distribution channels, pre-releases and maintenance releases

semantic-release can publish to different distribution channels, such as npm dist-tags, based on which branch was merged. It also supports pre-releases and maintenance releases. The README points to recipes for each of these workflows.

• Distribution channels: see the recipe on publishing on distribution channels
• Pre-releases: see the recipe on publishing pre-releases
• Maintenance releases: see the recipe on publishing maintenance releases

Configure plugins and shareable configurations

The tool supports any package manager and language through plugins. Configuration can be kept simple and reused through shareable configurations. The README also notes support for npm package provenance, which adds signed attestations on GitHub Actions.

The source excerpt is truncated before the full requirements and configuration details, so check the project documentation for exact configuration keys and plugin names.

• Plugins: see the plugins page on semantic-release.org
• Shareable configurations: see the shareable configurations page
• npm provenance: supported via signed attestations on GitHub Actions