semantic-release monorepo releases the wrong package in CI

semantic-release is designed for one package per repository. In a monorepo it analyzes all commits and tags on the branch, so a package can release from commits that did not touch it, or tags from other packages confuse version detection.

What this error means

A package publishes a new version even though only unrelated packages changed, or version detection picks up tags belonging to a different package in the same repo.

[semantic-release] Found git tag ui-v2.3.0 associated with version 2.3.0 on branch main
[semantic-release] The next release version is 2.4.0
# but only packages/api changed in these commits

Common causes

No per-package commit or tag filtering

Vanilla semantic-release does not scope analysis to a subdirectory, so every commit and every tag on the branch is considered.

Shared tag format across packages

Packages use overlapping tag formats, so one package reads another package tag as its last release.

How to fix it

Scope releases per package with a monorepo tool

1. Run semantic-release per package with commit paths filtered to that package.
2. Give each package a distinct tagFormat so tags do not collide.
3. Trigger a package release only when its files changed.

{
  "tagFormat": "api-v${version}"
}

Filter commits to the package path

Use a monorepo plugin or commit-analyzer path filtering so only commits touching the package trigger its release.

# run from each package dir with its own config
npx semantic-release --extends ./release.config.js

How to prevent it

• Use a distinct tagFormat per package in a monorepo.
• Filter commit analysis to each package path.
• Release a package only when its directory changed.

Related guides