Skip to content

Configuration Files

releasio supports multiple configuration file formats.

Supported Files

Dedicated configuration file with highest priority.

.releasio.toml
default_branch = "main"

[version]
tag_prefix = "v"

[changelog]
path = "CHANGELOG.md"

Use This When

  • You want configuration separate from pyproject.toml
  • You prefer a hidden file (dotfile)
  • You have complex configuration

releasio.toml

Visible configuration file.

releasio.toml
default_branch = "main"

[version]
tag_prefix = "v"

Use This When

  • You want visible configuration
  • Other tools use dotfiles and you want distinction

pyproject.toml

Configuration under [tool.releasio] section.

pyproject.toml
[tool.releasio]
default_branch = "main"

[tool.releasio.version]
tag_prefix = "v"

[tool.releasio.changelog]
path = "CHANGELOG.md"

Use This When

  • You want all Python config in one file
  • You have simple configuration
  • You're already using pyproject.toml

Priority Order

When multiple files exist, releasio uses this priority:

%%{init: {'theme': 'neutral'}}%%
graph LR
    A[.releasio.toml] --> B{Exists?}
    B -->|Yes| C[Use it]
    B -->|No| D[releasio.toml]
    D --> E{Exists?}
    E -->|Yes| F[Use it]
    E -->|No| G[pyproject.toml]
Priority File Notes
1 .releasio.toml Highest priority
2 releasio.toml Second priority
3 pyproject.toml Fallback

No Merging

Only one configuration source is used. Files are not merged together.

Format Differences

Standalone Files

Use top-level keys directly:

.releasio.toml
default_branch = "main"

[version]
tag_prefix = "v"

[changelog]
path = "CHANGELOG.md"

pyproject.toml

Requires [tool.releasio] prefix:

pyproject.toml
[tool.releasio]
default_branch = "main"

[tool.releasio.version]
tag_prefix = "v"

[tool.releasio.changelog]
path = "CHANGELOG.md"

Required: pyproject.toml

Even when using .releasio.toml, pyproject.toml is always required for:

  • Project name
  • Current version
  • Build system configuration
pyproject.toml (always needed)
[project]
name = "my-project"
version = "1.0.0"

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

Example Structure

my-project/
├── .releasio.toml      # Release configuration
├── pyproject.toml      # Project metadata
├── src/
│   └── my_project/
│       └── __init__.py
└── CHANGELOG.md

Validation

releasio validates configuration on load:

# Configuration errors are shown immediately
releasio check

Unknown keys cause errors (thanks to Pydantic's strict mode):

Error: Unknown configuration key 'unknwon_key' in [version]

This catches typos early!