Better Release PRs with brel

Mon, 16 Mar 2026 00:00:00 GMT

import Callout from '../../components/mdx/Callout.astro' I really like [release-plz](https://release-plz.dev/) for my Rust projects ([balzac](https://balzac.rs) uses it); it's easy to configure, it automatically updates the relevant version fields (in cargo.toml) and can even update the `CHANGELOG.md` of your repo. There's only one problem: it only works with Rust. So I decided to make my own. ## Better Releases [better releases](https://better-releases.com) is a tool that works on any Github repo, with any language and any stack. It uses a simple-ysh `brel.toml` file and: - reads the commit from the previous tag (if it exists) - figures out the next tag based on conventional commits - opens/updates a release pr Once the pr is merged, it can optionally publish the detected tag to potentially trigger other workflows; in the [drizzle-sluggable](https://github.com/matfire/drizzle-sluggable) repo, this is what I use to trigger publishing the package to npm. ## Getting Started To get started, you need to install `brel` (better-releases' main tool); if you don't want to, you can also run it with ```bash npx brel@latest init ``` The init command will ask some question to setup the base config and will generate the base workflow for Github Actions. Here's what the config file might look like ```toml default_branch = "main" ``` But we can do so much better than that. When modifying the config, you will need to rerun the init command to update the workflow file ### Bumping Package versions Honestly, this feature is why I decided to build this tool: I wanted to be able to update versions across toml and json files (Rust, Javascript, PHP) with a single tool. Let's see how we can do this. For a **package.json** file, we might want to bump the **version** field; with Brel, you can just do: ```toml [release_pr.version_updates] "package.json" = ["version"] ``` But that's not all! Imagine you want to update the version inside a lock file (though you probably shouldn't do this in CI), you can also pass selectors when selecting an array: ```toml [release_pr.version_updates] "Cargo.toml" = ["package.version"] "Cargo.lock" = ["package[name=brel].version"] ``` You might notice there's a **.lock** file in there; you can override the filetype like this: ```toml [release_pr.format_overrides] "Cargo.lock" = "toml" ``` ### Pushing a Tag Let's say we want to add automatic tag creation when merging the release branch; we can do so with a few config changes ```toml [release_pr.tagging] enabled = true tag_template = "{version}" ``` With this setup, merging the branch will create a tag corresponding to the version, like **0.7.0** To actually enable release tagging, you need to provide a token allowed to do so under the secret name BREL_TAG_PUSH_TOKEN ### Generating/Updating a Changelog When enabled, Brel integrates with [Git Cliff](https://git-cliff.org/) to automatically update a **CHANGELOG.MD** file. Here's how you might configure this: ```toml [release_pr.changelog] enabled = true output_file = "CHANGELOG.md" ``` This will automatically update the **CHANGELOG.md** file using [Git Cliff](https://git-cliff.org) ### There's more I will not bore you with everything Brel can do (you can even customize the template used for the pr body), but if you want to give it a try here's [the official website](https://better-releases.com) and the [github repo](https://github.com/better-releases/brel); do try it out if you have need of a tool like this and let me know what you think!