How brel Works

brel automates releases the way Release Please and release-plz do: instead of releasing on every merge, it maintains a release PR that always shows you the next release — its version, its changelog, its file changes — and releasing is simply merging that PR.

The lifecycle

 you merge work                     CI runs brel                you merge the
 to main                            release-pr                  release PR
──────────────►  Conventional  ──────────────►  "Release       ──────────────►  tag vX.Y.Z
                 Commits pile        Commits       vX.Y.Z" PR                       pushed
                 up on main          determine     stays up                        (opt-in)
                                     the bump      to date

1. You work normally. Land changes on the default branch using Conventional Commits: fix: means a patch, feat: a minor, and BREAKING CHANGE/! a major bump. Commits without those prefixes don’t trigger releases.

2. CI keeps a release PR fresh. On every push to the default branch, the workflow generated by brel init runs brel release-pr. brel computes the next version from the commits since the last release tag, bumps your version files, regenerates the changelog, and creates or updates a single managed PR titled Release vX.Y.Z. If nothing releasable landed, it does nothing.

3. You merge the release PR when ready. Nothing ships until you decide. The PR is the release preview: review the version, the changelog, the diff.

4. Optionally, the tag follows automatically. With tagging enabled, merging the release PR triggers brel tag, which tags the merge commit (v1.2.3 by default) and pushes it — ready to trigger whatever downstream release pipeline you have (binary builds, package publishing, deploys).

What brel does not do

brel deliberately stops at the tag. It doesn’t build artifacts, publish packages, or create forge “Releases” — those belong to your tag-triggered pipelines. It also doesn’t manage your changelog tool’s config (cliff.toml stays yours) and never lets changelogen commit, tag, or publish.

Where things run

brel is CI-first: brel init generates a managed workflow for GitHub Actions, GitLab CI, or Forgejo Actions. But every command also runs locally — useful for previewing (brel next-version, brel init --dry-run) or driving releases by hand.

Dig deeper

VersioningExactly how the next version is computed.

The Release PRBranch names, markers, and stale-PR migration.

Tagging on MergeEvent mode, manual mode, and push tokens.