Scope-Based Release Rules in semantic-release

Scope-Based Release Rules

You can configure semantic-release to trigger different release types based on the scope of a commit, giving you fine-grained control over versioning in projects with multiple modules or APIs.

Configuration

{
  "branches": ["main"],
  "plugins": [
    ["@semantic-release/commit-analyzer", {
      "preset": "angular",
      "releaseRules": [
        {"type": "feat", "scope": "api", "release": "minor"},
        {"type": "feat", "scope": "ui", "release": "minor"},
        {"type": "feat", "scope": "core", "release": "minor"},
        {"type": "fix", "scope": "api", "release": "patch"},
        {"type": "fix", "scope": "security", "release": "patch"},
        {"type": "feat", "scope": "deps", "release": "patch"},
        {"type": "refactor", "scope": "api", "release": "patch"},
        {"type": "perf", "scope": "*", "release": "patch"},
        {"type": "docs", "release": false},
        {"type": "test", "release": false},
        {"type": "ci", "release": false}
      ]
    }],
    "@semantic-release/release-notes-generator",
    "@semantic-release/npm",
    "@semantic-release/github"
  ]
}

Commit Examples

Commit Message	Matched Rule	Release
feat(api): add users endpoint	feat + api scope	minor
fix(security): patch XSS vulnerability	fix + security scope	patch
feat(deps): update lodash to v5	feat + deps scope	patch
refactor(api): restructure routes	refactor + api scope	patch
docs(readme): update installation	docs (any scope)	no release

Wildcard Scopes

Use "*" as the scope value to match any scope for a given commit type. This is useful as a catch-all after more specific rules.

Rule Evaluation Order

Rules are evaluated top-to-bottom. The first matching rule wins. Always place more specific rules (with scope) before general rules (without scope or with wildcard scope).

Breaking Changes Override

Note that BREAKING CHANGE in the commit footer always triggers a major release regardless of any scope-based rules. This ensures API-breaking changes are always properly versioned.