Why does plugin order matter?

semantic-release runs plugins in array order through lifecycle steps. commit-analyzer must run first to determine the version, release-notes-generator next, and the git plugin must come last so it commits the already-updated package.json and changelog.

How does semantic-release decide the next version?

The commit-analyzer plugin reads your commit messages using the Conventional Commits convention. A fix commit triggers a patch release, feat triggers a minor, and a BREAKING CHANGE footer triggers a major, so versioning is fully derived from history.

What tokens do I need to publish?

You need an NPM_TOKEN for the npm plugin and a GITHUB_TOKEN for the github plugin, both supplied as CI environment variables. semantic-release never stores secrets in the config file itself.

What does the git plugin do?

After a release, the git plugin commits the bumped package.json and updated CHANGELOG.md back to the repository and pushes. The [skip ci] tag in its commit message prevents that commit from triggering another release run.

Can I use this without publishing to npm?

Yes. Turn off the npm plugin to only create GitHub releases and changelogs. This is common for applications or private repos that version and tag releases but never publish a package to the public registry.

semantic-release Config Builder

Email me this result

Get this tool's output sent to your inbox, plus one useful tool a week. No spam, unsubscribe any time.

Automate releases with semantic-release

semantic-release removes manual version bumps entirely. It reads your commit history, figures out the right semantic version, generates release notes, publishes to npm, creates a GitHub release, and commits the changelog back — all from CI. The behavior is driven by .releaserc.json, and this builder produces a correct, ordered configuration.

How it works

The branches array lists which branches are allowed to trigger a release, typically main for stable plus channels like next for pre-releases. tagFormat controls the git tag, defaulting to v${version}.

The plugins array is an ordered pipeline, and order is the most important detail. commit-analyzer runs first to compute the next version from Conventional Commit messages — fix means patch, feat means minor, BREAKING CHANGE means major. release-notes-generator then renders notes. Optional plugins follow: changelog writes CHANGELOG.md, npm publishes the package, and github creates the release. The git plugin must come last so it commits the updated package.json and changelog back with a [skip ci] message to avoid an infinite loop.

Tips and notes

Keep git as the final plugin in the array, always.
Supply NPM_TOKEN and GITHUB_TOKEN as CI secrets — never in the config.
Disable the npm plugin for apps that release but should not publish a package.
Pair this with a commitlint config so every commit is parseable.