Configuration Reference

Complete reference for releasaurus.toml, environment variables, and supported languages. For guidance and examples, see Configuration.

Configuration is grouped under three top-level tables: [repository] (repo-wide settings), [defaults] (release defaults for every package, with [defaults.versioning] and [defaults.changelog] subtables), and one or more [[package]] entries. All keys are optional.

Unknown keys are rejected, so a misspelled or misplaced option fails at config load rather than being silently ignored.

[repository]

Repository-wide settings:

skip_shas and reword operate on the repository’s shared commit history, so they are repo-wide and cannot be overridden per package. A --reword for a SHA already listed in config takes precedence over the config entry.

[repository]
git_user = { name = "My User", email = "myuser@email.com" }
base_branch = "main"
tag_search_depth = 100
separate_pull_requests = false
skip_shas = ["abc123d", "def456e"]

[[repository.reword]]
sha = "abc123d"
message = "fix: corrected description"

[defaults]

Keys set directly on [defaults], rather than in one of its subtables. All four are Tera templates for the release commit message and PR title; see Commit Message & PR Title Templates for which one applies when.

The two contexts differ: branch and repo_name are always available, while package_name, tag, and semver exist only in the per-package templates. Referencing a variable that isn’t in scope is rejected at config load.

[defaults]
pr_title_template = "🚀 Release {{ package_name }} {{ tag }}"
monorepo_pr_title_template = "🚀 Release {{ repo_name }} ({{ branch }})"

[defaults.versioning]

Everything that affects the computed version, plus the commit filtering and grouping rules (which affect the version as well as the changelog). Each package may override these individually via its own versioning table (see [[package]]).

Custom increment regexes

custom_major_increment_regex and custom_minor_increment_regex are additive — breaking changes always bump major and feat: always bumps minor regardless. The pattern is matched against the full commit message. In TOML double-quoted strings, escape backslashes (\\):

[defaults.versioning]
custom_major_increment_regex = "\\[MAJOR\\]"   # matches "[MAJOR]"
custom_minor_increment_regex = "FEATURE"        # no escaping needed

The two are not symmetric. custom_major_increment_regex marks a matching commit breaking, which groups it under ❌ Breaking and marks it [**breaking**] in the default body template as well as bumping major. custom_minor_increment_regex only affects the version.

[defaults.versioning.named_parsers] breaking.pattern is the same mechanism as custom_major_increment_regex under a different name; set either, or both, in which case a commit matching either is breaking. See Commit Groups & Filtering.

An invalid pattern is rejected when the config loads, not part-way through a release.

[defaults.versioning.prerelease]

Default prerelease config; can be overridden per package via that package’s versioning.prerelease. See Prereleases. Applies only when version_type is major.minor.patch or major.minor.patch+timestamp.sha.

[defaults.versioning.prerelease]
suffix = "beta"
strategy = "versioned"

[defaults.versioning.named_parsers]

[defaults.versioning.named_parsers]
ci.skip = true
chore.skip = true
feature.title = "✨ New Stuff"
feature.order = 1

order (0-99, lowest first) sets the heading’s position in the changelog and is independent of the title text. See Ordering groups.

[[defaults.versioning.custom_parser]]

[[defaults.versioning.custom_parser]]
pattern = "^deps"
title = "📦 Dependencies"
order = 3
skip = false

pattern, title and order are all required — a custom group has no built-in position to fall back on.

[defaults.changelog]

Controls how the included commits are rendered. See Changelog Customization for the template and variables.

[defaults.changelog]
include_author = true
include_pr_link = true

include_pr_link is paid for per package: one that leaves it off costs no requests even when a sibling turns it on. Note that a custom body must carry the commit.pr clause itself; see Pull request links.

[[package]]

One entry per package; repeatable.

sub_packages entries take name, path, and release_type.

Versioning options are not direct package keys — they live under the package’s versioning table, mirroring [defaults.versioning]. For example, a per-package prerelease is versioning = { prerelease = { suffix = "alpha" } }, and the matching CLI override is --set-package <name>.versioning.prerelease.suffix=.

additional_manifest_files

Extra files whose version strings should be kept in sync — custom VERSION files, docs, config, etc. Accepts plain string paths (using a default regex) or objects with a custom version_regex. All paths are relative to the package path.

[[package]]
path = "."
release_type = "rust"
additional_manifest_files = [
    "VERSION",                    # default regex
    "README.md",                  # default regex
    { path = "helm/Chart.yaml", version_regex = "appVersion:\\s*\"?(?<version>\\d+\\.\\d+\\.\\d+)\"?" },
]

The default regex matches common forms like version = "1.0.0", version: "1.0.0", VERSION='1.0.0', and "version": "1.0.0". A custom version_regex must include a named capture group (?<version>...); only that group is replaced. Files without a match are skipped; an invalid regex errors during config resolution.

Per-package overrides

A package can carry its own versioning and changelog config, using exactly the same fields as [defaults.versioning] and [defaults.changelog]. Because packages are an array of tables ([[package]]), set them as inline tables on the package itself so they are unambiguously scoped to that entry — a separate [package.changelog] header would only ever bind to the most-recently-declared package:

[[package]]
name = "frontend"
path = "./apps/web"
release_type = "node"
changelog = { include_author = true }
versioning = { named_parsers = { ci = { skip = true } } }

Both merge field-by-field with their [defaults] counterpart. Any field you set on the package wins; any field you omit is inherited from [defaults], falling back to the built-in default only when [defaults] doesn’t set it either. So if [defaults.changelog] enables include_author and a package sets its own changelog without it, that package keeps include_author = true. include_pr_link merges the same way.

Two fields compose rather than replace:

• custom_parser — entries from [defaults] and the package are combined, with the package’s checked first.
• named_parsers — overrides apply per group and per field. Each group you list is merged onto the [defaults] value for that group, then onto the built-in default, so you only specify the fields you want to change. A package that only retitles ci still inherits ci.skip = true from [defaults].

One table replaces rather than merges:

• prerelease — a package’s prerelease table replaces the [defaults] one outright. suffix and strategy describe a single prerelease identity (rc + versioned, SNAPSHOT + static), so inheriting one field across a change to the other would produce combinations you didn’t ask for. Restate strategy alongside a package-level suffix whenever your default strategy isn’t the versioned built-in.

commit_message_template and pr_title_template are plain strings rather than tables, so there is nothing to merge: the package’s value wins, else the [defaults] value, else the built-in. Set them directly on the package, not inside a nested table. The monorepo_* templates have no package-level form at all — they describe a PR spanning several packages, so no one package owns them, and setting one on a [[package]] is a config error.

Complete Example

[repository]
base_branch = "main"
first_release_search_depth = 400
separate_pull_requests = false

[defaults]
pr_title_template = "🚀 Release {{ package_name }} {{ tag }}"
monorepo_pr_title_template = "🚀 Release {{ repo_name }}"

[defaults.versioning]
auto_start_next = false
version_type = "major.minor.patch"
breaking_always_increment_major = true
features_always_increment_minor = true

[defaults.versioning.prerelease]
suffix = "beta"
strategy = "versioned"

[defaults.versioning.named_parsers]
ci.skip = true
chore.skip = true

[[defaults.versioning.custom_parser]]
pattern = "^deps"
title = "📦 Dependencies"
order = 3
skip = false

[defaults.changelog]
include_author = false

[[package]]
name = "frontend"
path = "./apps/web"
release_type = "node"
tag_prefix = "web-v"
# Per-package overrides (merge over the [defaults.*] equivalents).
changelog = { include_author = true }

[[package]]
name = "backend"
path = "./services/api"
release_type = "rust"
tag_prefix = "api-v"
versioning = { prerelease = { suffix = "alpha", strategy = "versioned" } }
pr_title_template = "api: {{ tag }}"

Environment Variables

Releasaurus selects the auth token automatically from the --forge type; --token overrides it. The RELEASAURUS_* variables are fallbacks for their matching CLI flags, and flags always win.

For the auth token, each forge accepts two env vars: a RELEASAURUS_-prefixed name and the bare name. The prefixed name takes precedence. Prefer it on Gitea/Forgejo CI runners (including Codeberg), which auto-inject their own limited token into the bare *_TOKEN name and would otherwise shadow your PAT — see the CI/CD integration notes and this known limitation.

Required token scopes

RELEASAURUS_DEBUG and RELEASAURUS_DRY_RUN are enabled by any non-empty value (including false or 0); unset or empty to disable. The --debug / --dry-run flags always enable regardless of the variable.

Supported Languages

Set release_type on a package and Releasaurus updates the matching manifest and lock files. Lock files are updated when present, and all languages support workspace/monorepo layouts.