Skip to content

Branch-prefix strategy

The branch-prefix strategy inspects the subject line of the head commit on the default branch and picks a bump if the subject (a) looks like a merge commit and (b) contains a configured branch-name prefix. It is the default strategy because it works out-of-the-box on repos that merge via short-lived prefixed branches and use the default git merge behavior.

Default prefix-to-bump table

Substring in commit subject Bump
feature/ minor
bugfix/ or hotfix/ patch
anything else none, status unmapped_branch_prefix

A bump of none means the commit contributes nothing to the release decision. branch-prefix never produces a major bump. Promote to a new major version manually, or switch to Conventional Commits, which recognizes feat! and BREAKING CHANGE:.

Merge-commit detection

The strategy only fires on commits whose subject contains one of the default merge marks: the literal string Merge branch (the default git merge subject) or Merge pull request (GitHub's merge-commit subject). Commits without one of those marks are declined with no_merge_commit regardless of prefix. For example:

  • Standard git merge feature/foo → subject Merge branch 'feature/foo' into main → bump = minor ✓
  • GitHub's Merge pull request #N from user/feature/foo → bump = minor ✓
  • Direct pushes to the default branch → bump = none (no_merge_commit), unless patch_on_non_merge_commit is enabled (see below), in which case bump = patch.

The merge_mark_texts tuple is configurable (defaults to ("Merge branch", "Merge pull request")); adapt it for non-default merge-commit conventions (e.g. squash-merge prefixes).

Customizing the prefixes

The strategy reads its prefixes from the application's settings layer:

  • minor: tuple of prefixes that trigger a minor bump (default ("feature/",)).
  • patch: tuple of prefixes that trigger a patch bump (default ("bugfix/", "hotfix/")).
  • merge_mark_texts: tuple of substrings that mark a subject as a merge commit (default ("Merge branch", "Merge pull request")).
  • patch_on_non_merge_commit: when true, a plain (non-merge) commit on the default branch bumps patch instead of producing no bump (default false). Set via SEMVERTAG_BRANCH_PREFIX__PATCH_ON_NON_MERGE_COMMIT=true. Affects only the non-merge case; a merge commit with an unrecognized prefix still produces no bump.

These are set via the same pydantic-settings env-var mechanism used for tokens / endpoints. The provider docs describe the variable naming convention.

Head commit only

Like every strategy, branch-prefix sees only the head commit of the push that triggered the run. A run that fails after a bump-worthy merge must be re-run: the next push is judged on its own head, and the earlier bump is not recovered.

When to pick a different strategy

If your team commits Conventional Commits messages directly to the default branch (without merge commits), switch to Conventional Commits. That strategy reads the head commit's subject and body and does not depend on merge metadata.

Consumer integration

The strategy is selected per project via the strategy: input on the relevant provider's component / action. See:

  • GitLab CI: set strategy: branch-prefix on the include: - component: block.