Configuration

Releasaurus works great out-of-the-box with zero configuration, but provides extensive customization options through an optional releasaurus.toml configuration file. This file allows you to customize changelog generation, define multiple packages within a repository, and fine-tune the release process to match your project's specific needs.

Configuration File Location

Releasaurus looks for a releasaurus.toml file in your project's root directory. If no configuration file is found, sensible defaults are used that work for most single-package repositories.

my-project/
├── releasaurus.toml    # ← Configuration file (optional)
├── src/
├── README.md
└── ...

Configuration Structure

The configuration file uses TOML format with two main sections:

• [changelog] - Customizes changelog generation and formatting
• [[package]] - Defines packages within the repository (can have multiple)

Default Configuration

This is the default configuration that is used if there is no specific user defined configuration provided.

# releasaurus.toml using default changelog body configuration

[changelog]
header = ""
body = "{% if version -%}
    # [{{ version | trim_start_matches(pat="v") }}]({{ extra.release_link_base }}/{{ version }}) - {{ timestamp | date(format="%Y-%m-%d") }}
{% else -%}
    # [unreleased]
{% endif -%}
{% for group, commits in commits | filter(attribute="merge_commit", value=false) | group_by(attribute="group") %}
    ### {{ group | striptags | trim | upper_first }}
    {% for commit in commits %}
      {% if commit.breaking -%}
        {% if commit.scope %}_({{ commit.scope }})_ {% endif -%}[**breaking**]: {{ commit.message | upper_first }} [_({{ commit.id | truncate(length=8, end="") }})_]({{ extra.commit_link_base }}/{{ commit.id }})
        {% if commit.body -%}
        > {{ commit.body }}
        {% endif -%}
        {% if commit.breaking_description -%}
        > {{ commit.breaking_description }}
        {% endif -%}
      {% else -%}
        - {% if commit.scope %}_({{ commit.scope }})_ {% endif %}{{ commit.message | upper_first }} [_({{ commit.id | truncate(length=8, end="") }})_]({{ extra.commit_link_base }}/{{ commit.id -}})
      {% endif -%}
    {% endfor %}
{% endfor %}"
footer = "Generated by Releasaurus 🦕"

[[package]]
path = "."
tag_prefix = "v"

Changelog Configuration

The [changelog] section allows you to customize how changelogs are generated using Tera templating engine.

Available Templates

body (Required)

The main changelog content template. This defines how each release section is formatted.

header (Optional)

Static content to prepended to the top of the changelog.

footer (Optional)

Static content to append to the bottom of the changelog.

Example:

[changelog]
header = "# Changelog"
footer = "Company footer"

Monorepo with Multiple Packages

# Frontend package
[[package]]
path = "./apps/frontend"
tag_prefix = "frontend-v"

# Backend API
[[package]]
path = "./apps/api"
tag_prefix = "api-v"

# Shared library
[[package]]
path = "./packages/shared"
tag_prefix = "shared-v"

# CLI tool
[[package]]
path = "./packages/cli"
tag_prefix = "cli-v"

Next Steps

• Check Environment Variables for runtime configuration options
• Review Troubleshooting for common configuration issues