Configuration

brel is configured with a TOML file, conventionally brel.toml at the repository root.

Discovery

Config is resolved in this order:

--config <path> — when provided, the file must exist or the command errors.
brel.toml in the current directory.
.brel.toml in the current directory.

If no file is found, built-in defaults are used (commands like validate require a real file).

Unknown keys anywhere in the file are not fatal — they produce warnings, which brel validate prints as warning: lines.

Minimal 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 config with defaults

Only provider, default_branch, and workflow_file are top-level keys; everything else nests under [release_pr].

provider = "github"          # github | gitlab | forgejo | gitea
default_branch = "main"
workflow_file = "release-pr.yml"   # ".gitlab-ci.yml" when provider = "gitlab"

[release_pr]
release_branch_pattern = "brel/release/v{{version}}"
pr_template_file = ""        # unset by default; path to a Handlebars template

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

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

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

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

[release_pr.version_updates]
# "<repo-relative file>" = ["<selector>", ...]

[release_pr.format_overrides]
# "<repo-relative file>" = "json" | "toml"

Top-level keys

`provider`

The forge hosting your repository. One of "github" (default), "gitlab", "forgejo", or "gitea".

github, gitlab, and forgejo are fully supported.
gitea is accepted as a config value, but brel init, brel release-pr, and event-mode brel tag are not yet supported for it — see the Gitea guide.

`default_branch`

The branch release PRs target and CI triggers watch. Default: "main".

`workflow_file`

The CI workflow file brel init generates and manages. Default: "release-pr.yml" (placed in the forge’s workflow directory), or ".gitlab-ci.yml" when provider = "gitlab".

`[release_pr]`

`release_branch_pattern`

Branch name used for release PRs. Default: "brel/release/v{{version}}". Only the {{version}} token is supported.

`pr_template_file`

Optional repo-relative path to a Handlebars template for the PR body. Unset by default. See PR Body Templates.

`[release_pr.commit_author]`

Author identity for release commits.

Key	Default
`name`	`brel[bot]`
`email`	`brel[bot]@users.noreply.github.com`

`[release_pr.changelog]`

Key	Default	Description
`enabled`	`true`	Whether `brel changelog` generates a changelog.
`provider`	`"git-cliff"`	`"git-cliff"` or `"changelogen"`.
`output_file`	`"CHANGELOG.md"`	File the changelog is written to (and staged in the release commit when present).

[release_pr.changelog.changelogen] sets changelogen-specific options:

Key	Default	Description
`version`	`"0.6.2"`	changelogen version to run via `npx`. Omitted or empty uses the default; explicit values must be valid SemVer.

See Changelog Generation.

`[release_pr.tagging]`

Key	Default	Description
`enabled`	`false`	Opt in to tagging-on-merge in the generated workflow.
`tag_template`	`"v{version}"`	Rendered tag format. Accepts `{version}` (legacy `{{version}}` is normalized) and must contain exactly one version token.

See Tagging on Merge.

`[release_pr.version_updates]`

Maps exact repo-relative file paths to arrays of version selectors:

[release_pr.version_updates]
"package.json" = ["version"]
"Cargo.toml" = ["package.version"]
"Cargo.lock" = ["package[name=my-crate].version"]

Paths must be repo-relative — absolute paths and .. segments are rejected. See Version File Updates for the selector syntax.

`[release_pr.format_overrides]`

Forces the parser for files whose extension doesn’t reveal their format. Values are "json" or "toml", and each key must also appear in version_updates:

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

Real-world example

brel releases itself with this config:

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

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

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