Skip to content
brel

Tagging on Merge

Tagging is opt-in. When enabled, merging the release PR results in a release tag on the merge commit — created and pushed by brel tag running in your CI.

[release_pr.tagging]
enabled = true               # default: false
tag_template = "v{version}"  # default

The tag template

Section titled “The tag template”

tag_template controls how tags are rendered from versions:

  • It accepts the {version} token (the legacy {{version}} form is normalized to {version}).
  • It must contain exactly one version token.
  • The same template is used in reverse by versioning to find the last release tag, so changing it mid-project means older tags no longer match.

Examples: v{version} → v1.2.3; {version} → 1.2.3; release-{version} → release-1.2.3.

Event mode (CI)

Section titled “Event mode (CI)”

When tagging is enabled, the workflow generated by brel init adds a merge trigger. On merge of a pull request into the default branch, CI runs brel tag with no arguments. brel then:

  1. Reads the forge’s merge event payload (GITHUB_EVENT_PATH, or FORGEJO_EVENT_PATH on Forgejo; GitLab uses the commit-to-MR API on default-branch push pipelines).
  2. Checks that the merged PR/MR is managed by brel and titled Release <rendered-tag>.
  3. Validates the tag against tag_template, creates it at the merge commit if it doesn’t already exist, and pushes refs/tags/<tag> to origin.

If the merged PR isn’t a managed release PR, nothing happens.

Manual mode

Section titled “Manual mode”

You can create tags by hand at any time, even with tagging-on-merge disabled:

Terminal window
brel tag --tag v1.2.3 --target <git-rev>

If --target is omitted, HEAD is tagged. The tag is still validated against tag_template.

See the brel tag reference for all flags.