Quick Start

This guide takes a repository from no release automation to a self-updating release PR. It assumes GitHub; the flow is the same on GitLab and Forgejo, with forge-specific details covered in the forge guides.

1. Install brel — see Installation, e.g.:

   brew install better-releases/tap/brel

2. Create a brel.toml at the repository root:

   # 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"]

   Point version_updates at your real version files — Cargo.toml, pyproject.toml, whatever applies. See Version File Updates.

3. Validate the config and generate the CI workflow:

   brel validate
   brel init --yes

   brel init writes a managed workflow file (.github/workflows/release-pr.yml on GitHub). Run it without --yes for interactive prompts — forge, changelog provider, tagging — which it persists back into brel.toml.

4. Commit and push brel.toml and the workflow to main.

5. Ship. Land commits using Conventional Commits (feat:, fix:, feat!:). CI keeps a Release vX.Y.Z PR up to date with the bumped version files and changelog. Merge it to release — and with tagging enabled, the tag is pushed automatically.

Tip

Not sure what a command will do? brel init --dry-run shows a diff without writing, brel next-version prints the version the next release would get, and brel validate checks your config.

Next steps

How brel WorksThe release lifecycle from commit to tag.

Forge guidesTokens, secrets, and generated CI per forge.

Configuration referenceEvery brel.toml key and its default.