Configuration Reference¶

Complete reference for all releasio configuration options.

Quick Reference¶

Section	Option	Default	Description
General	`default_branch`	`"main"`	Default branch for releases
	`allow_dirty`	`false`	Allow dirty working directory
`[version]`	`tag_prefix`	`"v"`	Git tag prefix
	`initial_version`	`"0.1.0"`	First release version
	`version_files`	`[]`	Additional version files
	`auto_detect_version_files`	`false`	Auto-detect version files
	`update_lock_file`	`true`	Update lock file after bump
`[changelog]`	`enabled`	`true`	Enable changelog generation
	`path`	`"CHANGELOG.md"`	Changelog file path
	`use_github_prs`	`false`	Use PR-based changelog
	`show_authors`	`false`	Show commit authors
	`native_fallback`	`true`	Use native if git-cliff missing
`[commits]`	`types_minor`	`["feat"]`	Types triggering minor bump
	`types_patch`	`["fix", "perf"]`	Types triggering patch bump
	`breaking_pattern`	`"BREAKING[ -]CHANGE:"`	Breaking change pattern
`[github]`	`release_pr_branch`	`"releasio/release"`	Release PR branch name
	`release_pr_labels`	`["release"]`	PR labels
	`draft_releases`	`false`	Create draft releases
	`release_name_format`	`"{project} {tag}"`	Release title format
`[publish]`	`enabled`	`true`	Enable PyPI publishing
	`registry`	PyPI URL	Package registry
	`tool`	`"uv"`	Build/publish tool
	`trusted_publishing`	`true`	Use OIDC publishing
`[hooks]`	`pre_bump`	`[]`	Commands before bump
	`post_bump`	`[]`	Commands after bump
	`pre_release`	`[]`	Commands before release
	`post_release`	`[]`	Commands after release

General Settings¶

Top-level settings that apply to the entire release process.

`default_branch`¶

Type: string · Default: "main"

The default branch for releases.

default_branch = "main"

`allow_dirty`¶

Type: boolean · Default: false

Allow releases from a dirty working directory.

allow_dirty = false

Warning

Not recommended for production releases.

`[version]`¶

Version management settings.

`tag_prefix`¶

Type: string · Default: "v"

Prefix for git tags.

[version]
tag_prefix = "v"  # Creates tags like v1.0.0

`initial_version`¶

Type: string · Default: "0.1.0"

Version to use for the first release (when no tags exist).

[version]
initial_version = "0.1.0"

`pre_release`¶

Type: string | null · Default: null

Global pre-release identifier. Use for always creating pre-releases.

[version]
pre_release = "alpha"  # All releases are alpha

`version_files`¶

Type: list[path] · Default: []

Additional files to update with the version.

[version]
version_files = [
    "src/myproject/__init__.py",
    "docs/conf.py",
]

`auto_detect_version_files`¶

Type: boolean · Default: false

Automatically detect and update version files.

[version]
auto_detect_version_files = true

Searches for:

__init__.py with __version__
__version__.py
_version.py

`update_lock_file`¶

Type: boolean · Default: true

Update lock file after version bump.

[version]
update_lock_file = true

Supports: uv.lock, poetry.lock, pdm.lock

`[changelog]`¶

Changelog generation settings.

`enabled`¶

Type: boolean · Default: true

Enable changelog generation.

[changelog]
enabled = true

`path`¶

Type: path · Default: "CHANGELOG.md"

Path to the changelog file.

[changelog]
path = "CHANGELOG.md"

`template`¶

Type: string | null · Default: null

Custom git-cliff template (path or inline).

[changelog]
template = "cliff-template.toml"

`header`¶

Type: string | null · Default: null

Custom header for the changelog.

[changelog]
header = "# Release Notes\n\nAll notable changes to this project.\n"

`use_github_prs`¶

Type: boolean · Default: false

Use GitHub PR-based changelog (recommended for squash merge).

[changelog]
use_github_prs = true

`ignore_authors`¶

Type: list[string] · Default: [list of bots]

Authors to exclude from changelog.

[changelog]
ignore_authors = [
    "dependabot[bot]",
    "renovate[bot]",
]

`section_headers`¶

Type: dict[string, string] · Default: {...}

Custom section headers for each commit type.

[changelog.section_headers]
feat = "✨ New Features"
fix = "🐛 Bug Fixes"
perf = "⚡ Performance"
docs = "📚 Documentation"
breaking = "⚠️ Breaking Changes"

`show_authors`¶

Type: boolean · Default: false

Include author names in changelog entries.

[changelog]
show_authors = true

`show_commit_hash`¶

Type: boolean · Default: false

Include short commit hash in changelog entries.

[changelog]
show_commit_hash = true

`commit_template`¶

Type: string | null · Default: null

Custom template for each commit entry.

[changelog]
commit_template = "- {description} ({hash}) by @{author}"

Available variables: {scope}, {description}, {author}, {hash}, {body}, {type}

`show_first_time_contributors`¶

Type: boolean · Default: false

Highlight first-time contributors.

[changelog]
show_first_time_contributors = true
first_contributor_badge = "🎉 First contribution!"

`include_dependency_updates`¶

Type: boolean · Default: false

Include dependency updates section.

[changelog]
include_dependency_updates = true

`native_fallback`¶

Type: boolean · Default: true

Generate changelog natively if git-cliff unavailable.

[changelog]
native_fallback = true

`[commits]`¶

Commit parsing and version bump rules.

`types_minor`¶

Type: list[string] · Default: ["feat"]

Commit types that trigger a minor version bump.

[commits]
types_minor = ["feat"]

`types_patch`¶

Type: list[string] · Default: ["fix", "perf"]

Commit types that trigger a patch version bump.

[commits]
types_patch = ["fix", "perf", "docs", "refactor"]

`types_major`¶

Type: list[string] · Default: []

Commit types that trigger a major version bump.

[commits]
types_major = []  # Usually empty; use breaking_pattern instead

`breaking_pattern`¶

Type: string · Default: "BREAKING[ -]CHANGE:"

Regex pattern to detect breaking changes in commit body.

[commits]
breaking_pattern = "BREAKING[ -]CHANGE:"

`scope_regex`¶

Type: string | null · Default: null

Only process commits matching this scope (for monorepos).

[commits]
scope_regex = "^(api|core)$"

`skip_release_patterns`¶

Type: list[string] · Default: ["[skip release]", ...]

Patterns in commit messages that skip release.

[commits]
skip_release_patterns = [
    "[skip release]",
    "[release skip]",
    "[no release]",
]

`commit_parsers`¶

Type: list[CommitParser] · Default: []

Custom commit parsers for non-conventional formats.

[[commits.commit_parsers]]
pattern = "^:sparkles:\\s*(?P<description>.+)$"
type = "feat"
group = "Features"

[[commits.commit_parsers]]
pattern = "^:bug:\\s*(?P<description>.+)$"
type = "fix"
group = "Bug Fixes"

`use_conventional_fallback`¶

Type: boolean · Default: true

Fall back to conventional commit parsing if no custom parser matches.

[commits]
use_conventional_fallback = true

`[github]`¶

GitHub integration settings.

`owner` / `repo`¶

Type: string | null · Default: null (auto-detected)

Repository owner and name.

[github]
owner = "myorg"
repo = "myproject"

`api_url`¶

Type: string · Default: "https://api.github.com"

GitHub API URL (for GitHub Enterprise).

[github]
api_url = "https://github.mycompany.com/api/v3"

`release_pr_branch`¶

Type: string · Default: "releasio/release"

Branch name for release PRs.

[github]
release_pr_branch = "releasio/release"

`release_pr_labels`¶

Type: list[string] · Default: ["release"]

Labels to apply to release PRs.

[github]
release_pr_labels = ["release", "automated"]

`draft_releases`¶

Type: boolean · Default: false

Create releases as drafts.

[github]
draft_releases = true

`release_name_format`¶

Type: string · Default: "{project} {tag}"

Format for GitHub release title. Customize how the release name appears on the GitHub releases page.

[github]
release_name_format = "{project} {tag}"  # "myapp v1.0.0" (default)

Available variables:

{project} - Project name from pyproject.toml (e.g., myapp)
{version} - Version number without prefix (e.g., 1.0.0)
{tag} - Full git tag including prefix (e.g., v1.0.0)

Examples:

[github]
# Just version number
release_name_format = "{version}"  # → "1.0.0"

# Version with prefix only
release_name_format = "{tag}"  # → "v1.0.0"

# Project and version (no prefix)
release_name_format = "{project} {version}"  # → "myapp 1.0.0"

# Custom format
release_name_format = "Release {version}"  # → "Release 1.0.0"

# With emoji
release_name_format = "🚀 {project} {tag}"  # → "🚀 myapp v1.0.0"

`release_assets`¶

Type: list[string] · Default: []

Files to upload as release assets (supports glob).

[github]
release_assets = [
    "dist/*.whl",
    "dist/*.tar.gz",
]

`[publish]`¶

PyPI publishing settings.

`enabled`¶

Type: boolean · Default: true

Enable PyPI publishing.

[publish]
enabled = true

`registry`¶

Type: string · Default: "https://upload.pypi.org/legacy/"

PyPI registry URL.

[publish]
registry = "https://test.pypi.org/legacy/"  # TestPyPI

`tool`¶

Type: "uv" | "poetry" | "pdm" | "twine" · Default: "uv"

Tool to use for building and publishing.

[publish]
tool = "uv"

`trusted_publishing`¶

Type: boolean · Default: true

Use OIDC trusted publishing when available.

[publish]
trusted_publishing = true

`validate_before_publish`¶

Type: boolean · Default: true

Run validation (twine check) before publishing.

[publish]
validate_before_publish = true

`check_existing_version`¶

Type: boolean · Default: true

Check if version already exists on PyPI.

[publish]
check_existing_version = true

`[hooks]`¶

Release lifecycle hooks.

`pre_bump`¶

Type: list[string] · Default: []

Commands to run before version bump.

[hooks]
pre_bump = ["npm run lint", "pytest"]

`post_bump`¶

Type: list[string] · Default: []

Commands to run after version bump.

[hooks]
post_bump = ["npm run build"]

`pre_release`¶

Type: list[string] · Default: []

Commands to run before release.

[hooks]
pre_release = ["./scripts/pre-release.sh"]

`post_release`¶

Type: list[string] · Default: []

Commands to run after release.

[hooks]
post_release = ["./scripts/notify-slack.sh {version}"]

`build`¶

Type: string | null · Default: null

Custom build command.

[hooks]
build = "make build VERSION={version}"

Available variables: {version}, {project_path}

`[security]`¶

Security advisory settings.

`enabled`¶

Type: boolean · Default: false

Enable security advisory integration.

[security]
enabled = true

`auto_create_advisory`¶

Type: boolean · Default: true

Automatically create GitHub Security Advisories.

[security]
auto_create_advisory = true

`security_patterns`¶

Type: list[string] · Default: [...]

Regex patterns to detect security commits.

[security]
security_patterns = [
    "fix\\(security\\):",
    "security:",
    "CVE-\\d{4}-\\d+",
]

`[branches]`¶

Multi-channel release configuration.

[branches.main]
match = "main"
prerelease = false

[branches.beta]
match = "beta"
prerelease = true
prerelease_token = "beta"

[branches.alpha]
match = "alpha/*"
prerelease = true
prerelease_token = "alpha"

`match`¶

Branch name or glob pattern.

`prerelease`¶

Whether releases are pre-releases.

`prerelease_token`¶

Pre-release identifier (e.g., "alpha", "beta", "rc").

Configuration Reference¶

Quick Reference¶

General Settings¶

default_branch¶

allow_dirty¶

[version]¶

tag_prefix¶

initial_version¶

pre_release¶

version_files¶

auto_detect_version_files¶

update_lock_file¶

[changelog]¶

enabled¶

path¶

template¶

header¶

use_github_prs¶

ignore_authors¶

section_headers¶

show_authors¶

show_commit_hash¶

commit_template¶

show_first_time_contributors¶

include_dependency_updates¶

native_fallback¶

[commits]¶

types_minor¶

types_patch¶

types_major¶

breaking_pattern¶

scope_regex¶

skip_release_patterns¶

commit_parsers¶

use_conventional_fallback¶

[github]¶

owner / repo¶

api_url¶

release_pr_branch¶

release_pr_labels¶

draft_releases¶

release_name_format¶

release_assets¶

[publish]¶

enabled¶

registry¶

tool¶

trusted_publishing¶

validate_before_publish¶

check_existing_version¶

[hooks]¶

pre_bump¶

post_bump¶

pre_release¶

post_release¶

build¶

[security]¶

enabled¶

auto_create_advisory¶

security_patterns¶

[branches]¶

match¶

prerelease¶

prerelease_token¶

`default_branch`¶

`allow_dirty`¶

`[version]`¶

`tag_prefix`¶

`initial_version`¶

`pre_release`¶

`version_files`¶

`auto_detect_version_files`¶

`update_lock_file`¶

`[changelog]`¶

`enabled`¶

`path`¶

`template`¶

`header`¶

`use_github_prs`¶

`ignore_authors`¶

`section_headers`¶

`show_authors`¶

`show_commit_hash`¶

`commit_template`¶

`show_first_time_contributors`¶

`include_dependency_updates`¶

`native_fallback`¶

`[commits]`¶

`types_minor`¶

`types_patch`¶

`types_major`¶

`breaking_pattern`¶

`scope_regex`¶

`skip_release_patterns`¶

`commit_parsers`¶

`use_conventional_fallback`¶

`[github]`¶

`owner` / `repo`¶

`api_url`¶

`release_pr_branch`¶

`release_pr_labels`¶

`draft_releases`¶

`release_name_format`¶

`release_assets`¶

`[publish]`¶

`enabled`¶

`registry`¶

`tool`¶

`trusted_publishing`¶

`validate_before_publish`¶

`check_existing_version`¶

`[hooks]`¶

`pre_bump`¶

`post_bump`¶

`pre_release`¶

`post_release`¶

`build`¶

`[security]`¶

`enabled`¶

`auto_create_advisory`¶

`security_patterns`¶

`[branches]`¶

`match`¶

`prerelease`¶

`prerelease_token`¶