brel

brel is a CLI that scaffolds and runs the better-releases workflow.

Install

Choose the install path that fits how you want to use brel:

Install from crates.io:

cargo install brel

Install with Homebrew:

brew install better-releases/tap/brel

Run the published npm package once with npx:

npx brel@latest --help

Install the latest prebuilt binary with the release shell script:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/better-releases/brel/releases/latest/download/brel-installer.sh | sh

Download a platform archive directly from the latest release page.

Install from this checkout while developing locally:

cargo install --path .

Quick Start

Create a brel.toml for the most basic release-pr setup:

# GitHub is the default provider, but keeping it explicit makes the file clearer.
provider = "github"

# Release PRs target this branch.
default_branch = "main"

[release_pr.version_updates]
# Update the root package version in package.json on each release PR.
"package.json" = ["version"]

Then validate the config and generate the managed workflow:

brel validate
brel init --yes

Commands

• brel init generates a managed GitHub Actions workflow or GitLab CI pipeline.
• brel changelog computes the next version and runs the configured changelog provider.
• brel release-pr computes the next version, updates configured files, commits, pushes, and creates/updates a release PR.
• brel tag creates and pushes a release tag, either from explicit --tag/--target args or from provider merge event data.
• brel next-version computes the next releasable version and prints it as plain SemVer.
• brel validate validates a config file and prints warnings for ignored keys.

Command Prerequisites

• git must be available.
• With provider = "github", brel release-pr requires gh (GitHub CLI).
• With provider = "github", brel release-pr requires a GitHub token in GH_TOKEN or GITHUB_TOKEN.
  • The workflow generated by brel init sets GH_TOKEN: ${{ github.token }} automatically.
• With provider = "gitlab", brel release-pr and GitLab event-mode tagging require BREL_GITLAB_TOKEN.
  • In GitLab CI, add BREL_GITLAB_TOKEN as a masked CI/CD variable with API and repository write access.
  • GitLab CI provides the project and commit metadata through predefined CI_* variables.
• brel changelog requires the configured provider runtime:
  • git-cliff for provider = "git-cliff"
  • npx for provider = "changelogen"
• The workflow generated by brel init installs the needed changelog runtime before running brel changelog.

Config File

brel discovers config in this order:

1. --config <path> (when provided)
2. brel.toml
3. .brel.toml

Use brel validate to check that an existing config file parses and satisfies the current schema before running other commands.

Minimal release-pr config

# GitHub is the default provider, but keeping it explicit makes the file clearer.
provider = "github"

# Release PRs target this branch.
default_branch = "main"

[release_pr.version_updates]
# Update the root package version in package.json on each release PR.
"package.json" = ["version"]

Full release_pr config

[release_pr.version_updates]
"package.json" = ["version"]
"Cargo.toml" = ["package.version"]
"release.yaml" = ["release.version"]

[release_pr.format_overrides]
"Cargo.toml" = "toml"

[release_pr]
release_branch_pattern = "brel/release/v{{version}}"
pr_template_file = ".github/brel/release-pr-body.hbs"

[release_pr.changelog]
enabled = true
provider = "git-cliff"
output_file = "CHANGELOG.md"

[release_pr.changelog.changelogen]
version = "0.6.2"

[release_pr.tagging]
enabled = false
tag_template = "v{version}"

[release_pr.commit_author]
name = "brel[bot]"
email = "brel[bot]@users.noreply.github.com"

How Versioning Works

When you run brel release-pr:

1. It finds the highest stable SemVer tag that matches release_pr.tagging.tag_template (default v{version}).
2. If no valid tag exists, it uses 0.0.0.
3. It scans commits since that tag (or all commits when no tag exists).
4. It picks one bump level from Conventional Commit signals:
   • major: BREAKING CHANGE in body/footer, or ! in the type/scope prefix.
   • minor: feat: ...
   • patch: fix: ...
5. If no releasable commits are found, it exits successfully with no changes.

brel next-version uses the same versioning rules:

• when releasable commits exist, it prints the next version (for example 1.2.3)
• when none exist, it prints nothing and exits successfully

How File Updates Work

• release_pr.version_updates maps exact repo-relative file paths to selector paths.
• Selector syntax:
  • key: version
  • nested key: package.version
  • index selector: packages[0].version
  • filter selector: package[name=brel].version
• Supported file formats:
  • inferred from extension (.json, .toml, .yaml, .yml)
  • or forced via release_pr.format_overrides
• Updates are fail-fast. The command errors if:
  • a file is missing,
  • format cannot be determined,
  • parse fails,
  • a selector is invalid,
  • a selector matches no values,
  • a selector uses index/filter on a non-array segment,
  • a matched value is not a string,
  • a YAML matched value uses block scalar syntax (| or >).
• Match behavior:
  • all values matched by a selector are updated
  • selectors do not create missing keys/paths

Example selectors:

• JSON: "package.json" = ["version", "tooling.release.version"]
• JSON with filter: "package.json" = ["package[name=brel].version"]
• TOML: "Cargo.toml" = ["package.version"]
• YAML: "release.yaml" = ["release.version", "packages[name=brel].version"]
• Cargo.lock (explicit format override required):

[release_pr.version_updates]
"Cargo.lock" = ["package[name=brel].version"]

[release_pr.format_overrides]
"Cargo.lock" = "toml"

Changelog Generation

• brel changelog computes the next release using the same versioning rules as brel next-version.
• If changelog generation is disabled, or if no releasable commits exist, brel changelog exits successfully without changing files.
• Configure changelog behavior with [release_pr.changelog]:
  • enabled (default true)
  • provider (default "git-cliff", also supports "changelogen")
  • output_file (default "CHANGELOG.md")
• Configure changelogen-specific behavior with [release_pr.changelog.changelogen]:
  • version (default "0.6.2"; omitted or empty uses the default; explicit values must be SemVer)
• git-cliff behavior:
  • runs git-cliff --config cliff.toml --unreleased --tag <rendered-tag> --prepend <output_file>
  • the generated workflow installs git-cliff with taiki-e/install-action@git-cliff
• changelogen behavior:
  • runs npx --yes changelogen@<configured-version> --to HEAD -r <next-version> --output <output_file>
  • the generated workflow sets up Node with actions/setup-node@v6
  • does not ask changelogen to bump versions, commit, tag, push, publish, or create GitHub releases
• If changelog generation is enabled, brel release-pr stages output_file in the release commit when that file exists.
• Enable changelogen:

[release_pr.changelog]
provider = "changelogen"

[release_pr.changelog.changelogen]
version = "0.6.2"

• Disable changelog generation:

[release_pr.changelog]
enabled = false

• brel init does not create or manage changelog tool config files. Keep cliff.toml in your repository for custom git-cliff rules, or use changelogen's supported config files (changelog.config.*, .changelogrc, or package.json's changelog field) for custom changelogen behavior.

Branch / Commit / PR Behavior

• Default branch pattern: brel/release/v{{version}}
  • Only {{version}} is supported as a token.
• release_pr.tagging.tag_template controls rendered release tags (default v{version}).
  • tag_template accepts {version} and legacy {{version}} (normalized to {version}).
  • tag_template must include exactly one version token.
• Commit message: chore(release): <rendered-tag>
• PR title: Release <rendered-tag>
• Commit author defaults to:
  • name = "brel[bot]"
  • email = "brel[bot]@users.noreply.github.com"
• Push strategy: --force-with-lease to origin.

For PRs/MRs:

• On GitHub, brel uses gh pr list to find an open managed release PR.
• On GitLab, brel uses GitLab's REST API to find an open managed release MR.
• If found on the current rendered release branch, it updates that PR/MR.
• If found on a stale release branch, it creates or updates the current rendered-branch PR/MR first, closes the stale PR/MR, and best-effort deletes the stale remote branch.
• If not found, it creates a new PR/MR.

Tagging on Merge

• Optional config: [release_pr.tagging] enabled = true (default false).
• Tag format config: [release_pr.tagging] tag_template = "v{version}" (default shown).
• When enabled, the generated GitHub workflow listens for merged pull requests into the configured default branch.
• The generated GitLab pipeline runs brel tag on default-branch push pipelines and uses GitLab's commit-to-MR API to detect managed merged release MRs.
• If the merged PR/MR is managed by brel and titled Release <rendered-tag>, brel tag creates the release tag.
• brel tag validates the tag against tag_template, creates it at the merge commit when missing, and pushes refs/tags/<tag> to origin.
• For GitHub, create repository secret BREL_TAG_PUSH_TOKEN before using tagging-on-merge.
  • Use a PAT that can push tags to the repository (fine-grained PAT with Contents: Read and write).
  • This is required because pushes done with GITHUB_TOKEN do not trigger downstream tag-push workflows.
• For GitLab, the generated pipeline uses BREL_GITLAB_TOKEN for API calls and git pushes.
• brel init prints the relevant token requirement for the configured provider.

Manual tag creation:

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

Manual mode can be used even when tagging-on-merge is disabled. If --target is omitted, HEAD is tagged.

PR Body Templates

If release_pr.pr_template_file is set, brel renders that Handlebars template.

Available variables:

• version
• tag
• base_branch
• release_branch
• commits (array of { sha_short, subject })

Important: include this marker in your template so future runs can detect and update the same PR:

<!-- managed-by: brel -->

If rendering fails, brel release-pr exits with an error.

Typical Usage

Generate workflow once:

brel init --yes

Run release locally:

git-cliff --version # or ensure npx is available when using changelogen
brel changelog
GH_TOKEN=... brel release-pr

For GitLab local runs, provide the same metadata normally supplied by GitLab CI:

BREL_GITLAB_TOKEN=... CI_API_V4_URL=https://gitlab.com/api/v4 CI_PROJECT_ID=123 brel release-pr

Run with explicit config:

brel changelog --config ./configs/release.toml
brel release-pr --config ./configs/release.toml

Validate config:

brel validate

Preview the next release version:

brel next-version

Create a tag manually:

brel tag --tag v1.2.3 --target HEAD