GitHub

Fully supported — release PRs, changelog, tagging-on-merge, and brel init all work on GitHub. GitHub is also brel’s default provider.

Prerequisites

• git available wherever brel runs.
• For local brel release-pr runs: the gh CLI and a token in GH_TOKEN or GITHUB_TOKEN. In the generated workflow, GH_TOKEN: ${{ github.token }} is set automatically and gh is preinstalled on GitHub runners.

Setup

1. Install brel and create a brel.toml at the repository root:

   provider = "github"
   default_branch = "main"
   
   [release_pr.version_updates]
   "package.json" = ["version"]

2. Generate the managed workflow:

   brel validate
   brel init --yes

   This writes .github/workflows/release-pr.yml (name configurable via workflow_file). Rerun brel init after config changes to regenerate it; --dry-run shows the diff first.

3. Commit both files and push to main. From now on, every push to main runs brel release-pr and keeps a release PR up to date.

4. Merge the release PR when you’re ready to ship.

What the generated workflow does

The managed release-pr.yml (marked # managed-by: brel):

• Triggers on pushes to your default branch and on workflow_dispatch.
• Checks out with full history (fetch-depth: 0 — required for version computation).
• Installs brel with the better-releases/setup-brel@v1 action.
• Installs the changelog runtime when enabled: git-cliff via taiki-e/install-action, or Node 24 for changelogen.
• Runs brel changelog then brel release-pr with GH_TOKEN: ${{ github.token }}.

Tagging on merge

If you enable [release_pr.tagging] and rerun brel init, the workflow gains a pull_request: closed trigger and a release-tag job that runs brel tag when a managed release PR merges.

Caution

Before enabling tagging-on-merge, create a repository secret named BREL_TAG_PUSH_TOKEN containing a fine-grained PAT with Contents: Read and write. Tags pushed with the default GITHUB_TOKEN do not trigger downstream tag-push workflows, so your release pipeline (e.g. one that builds binaries on v* tags) would never run. The generated job fails fast with a clear message if the secret is missing.

Running locally

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

See Environment Variables for the full list.