Introduction

Releasaurus 🦕 is a comprehensive release automation tool that works out-of-the-box with zero configuration required. Simply point it at your repository to get automated changelog generation and git tagging, or add a minimal config file to enable version file updates across multiple programming languages and Git forge platforms.

Get Started in Seconds

Releasaurus works immediately without any setup:

# Create a release PR (no config file needed!)
releasaurus release-pr \
  --forge github \
  --repo "https://github.com/your-org/your-repo"

# After merging the PR, publish the release
releasaurus release \
  --forge github \
  --repo "https://github.com/your-org/your-repo"

That’s it! Releasaurus analyzes your commit history, generates a changelog, and creates a release—no configuration file required.

When You Need More

Add a releasaurus.toml file when you want:

• Version file updates - Automatically update package.json, Cargo.toml, pom.xml, etc.
• Monorepo support - Manage multiple independently-versioned packages
• Custom changelog templates - Tailor formatting to your needs
• Custom tag prefixes - Use tags like api-v1.0.0 or cli-v2.1.0

See the Configuration guide for details.

Key Features

🚀 Zero Configuration by Default

Works immediately for changelog generation and git tagging. Add configuration only when you need version file updates or custom settings.

🌍 Multi-Platform Support

Works with GitHub, GitLab, and Gitea, whether hosted or self-hosted instances. One tool for all your repositories, regardless of where they’re hosted.

📦 Multi-Language Version Updates

When configured, updates version files for:

• Rust (Cargo.toml)
• Node.js (package.json, package-lock.json, yarn.lock)
• Python (pyproject.toml, setup.py, setup.cfg, requirements files)
• Java (Maven pom.xml, Gradle build files)
• PHP (composer.json)
• Ruby (Gemfile, .gemspec files)
• Generic projects (custom version file patterns)

🎯 Command-Line Overrides

Test configurations, create emergency releases, or use different prerelease settings without modifying your config file. Override base branch, prerelease settings, and per-package configurations directly from the command line—perfect for CI/CD environments with multiple deployment targets.

See Configuration Overrides for details.

📁 Forge API Integration

Works entirely through forge platform APIs—no local repository cloning required. Analyzes commits, creates branches, and manages releases directly via API calls, making it ideal for CI/CD environments and remote automation.

📝 Smart Changelog Generation

Inspired by git-cliff, automatically generates beautiful changelogs from your commit history with conventional commit support.

🏢 Monorepo Ready

Handle multiple independently-versioned packages within a single repository with per-package configuration and release cycles.

🤖 CI/CD Integration

Complete automation through official integrations:

• GitHub Actions: GitHub Actions Integration
• GitLab CI/CD: GitLab CI/CD Integration
• Gitea Actions: Gitea Actions Integration

Automatically create release PRs on push and publish releases when merged—no manual intervention required.

How It Works

Core Workflow (2 Steps)

1. releasaurus release-pr - Analyzes your commits, determines the next version, updates version files (if configured), generates a changelog, and creates a pull request for review.

2. releasaurus release - After the release PR is merged, creates a Git tag and publishes the release to your forge platform.

This workflow provides a safety net through pull request reviews while automating all the tedious version management tasks.

Optional Enhancements

• releasaurus start-next - Automatically bump patch versions after release to start the next development cycle. Perfect for continuous development workflows.

• releasaurus show - Query release information for automation, CI/CD pipelines, and custom notifications without making any changes.

What Problems Does Releasaurus Solve?

For Teams Across Multiple Platforms

• Stuck on GitHub but want to migrate to GitLab or self-hosted Gitea?
• Managing repositories across different forge platforms?
• Need a single release tool that works everywhere?

For Multi-Language Projects

• Managing releases across Rust, Node.js, Python, and Java projects?
• Want consistent release workflows regardless of language?
• Need automatic version file updates across different ecosystems?

For Flexibility and Control

• Need zero-config changelog generation without setup files?
• Want to test prerelease configurations before committing changes?
• Need different release settings for dev/staging/prod environments?
• Looking for command-line overrides for emergency releases?

For Monorepo Management

• Managing multiple packages with independent version numbers?
• Need separate or combined release PRs for different packages?
• Want per-package prerelease configurations?

Releasaurus addresses these challenges by providing universal platform support, multi-language compatibility, minimal configuration, and flexible command-line overrides.

Credit and Inspiration

Releasaurus was inspired by excellent tools like git-cliff, release-please, and release-plz. We’re grateful for the foundation these projects provided and have built upon their proven concepts while extending support to a broader ecosystem of languages, frameworks, and platforms.

Getting Started

Ready to automate your releases?

• Quick start: Jump to Quick Start to see Releasaurus in action
• Installation: See Installation for setup instructions
• Configuration: Check Configuration when you need version file updates or custom settings

Whether you’re maintaining a single-language project or a complex monorepo, Releasaurus adapts to your workflow while maintaining the reliability and safety that production releases demand.

Installation

Get Releasaurus installed and running in under a minute.

Fastest: Pre-built Binary (Recommended)

Install via cargo-binstall for the quickest setup:

cargo binstall releasaurus

This downloads a pre-compiled binary—much faster than compiling from source.

Alternative Methods

From Crates.io

Install and compile from Rust’s package registry:

cargo install releasaurus

This compiles from source, which takes longer but ensures compatibility with your system.

From Source

Build the latest development version:

git clone https://github.com/robgonnella/releasaurus.git
cd releasaurus
cargo install --path .

Prerequisites: Rust 1.80+ and Git

Docker

Use the official Docker image:

# Pull the image
docker pull rgonnella/releasaurus:latest

# Run commands
docker run --rm rgonnella/releasaurus:latest --help

Manual Binary Download

Download pre-built binaries directly from the releases page.

Verify Installation

Confirm Releasaurus is working:

releasaurus --version

Next Steps

→ Ready to go? See the Quick Start guide to release your first project in under 2 minutes.

→ Need configuration? Check out Configuration for version file updates and custom settings.

Quick Start

Get Releasaurus running in under 2 minutes with zero configuration.

Test Locally (No Setup Required)

Try Releasaurus on any git repository without tokens or configuration:

# 1. Navigate to any git repository
cd /path/to/your/repo

# 2. Run Releasaurus locally
releasaurus release-pr --forge local --repo "."

# 3. Review the output
# - See what version would be released
# - View the generated changelog
# - No changes made to your repository

That’s it! You’ve just seen what Releasaurus would do without any risk.

Go Live in 3 Steps

Ready to create an actual release? Here’s the full workflow:

1. Set Your Access Token

# GitHub
export GITHUB_TOKEN="ghp_your_token_here"

# GitLab
export GITLAB_TOKEN="glpat_your_token_here"

# Gitea
export GITEA_TOKEN="your_token_here"

See Environment Variables for token setup details.

2. Create a Release PR

releasaurus release-pr \
  --forge github \
  --repo "https://github.com/your-org/your-repo"

This analyzes commits, generates a changelog, and creates a pull request.

3. Merge PR, Then Publish

After merging the pull request:

releasaurus release \
  --forge github \
  --repo "https://github.com/your-org/your-repo"

This creates a git tag and publishes the release.

Need Version File Updates?

By default, Releasaurus only creates changelogs and tags. To update version files (package.json, Cargo.toml, etc.), add a releasaurus.toml:

[[package]]
path = "."
release_type = "node"  # or rust, python, java, php, ruby

See Configuration for all options.

Next Steps

• Commands - All commands and options including dry-run mode, CLI overrides, and the start-next command
• CI/CD Integration - Automate with GitHub Actions, GitLab CI, or Gitea Actions
• Configuration - Monorepo support, custom changelogs, prerelease versions, and more
• Troubleshooting - Common issues and solutions

Commands

Releasaurus provides commands for release automation and inspection to create a safe, reviewable release process. The goal is to help ensure that all changes are reviewed before publication while automating the tedious aspects of version management and changelog generation.

Important: Releasaurus operates entirely through forge platform APIs without requiring local repository clones. You can run these commands from any location with network access to your forge platform.

Command Overview

release-pr

Purpose: Analyze commits, update versions, generate changelog, and create a pull request

This command does the heavy lifting of release preparation:

• Analyzes commits since the last release
• Determines the appropriate version bump (patch, minor, major)
• Updates version files across your project
• Generates a changelog from commit history
• Creates a pull request with all changes
• Supports prerelease versions (alpha, beta, rc, etc.)
• Supports dry-run mode for testing

release

Purpose: Create tags and publish the release after PR approval

This command finalizes the release:

• Validates that you’re on a release commit
• Creates a Git tag for the new version
• Pushes the tag to the remote repository
• Creates a release on your forge platform
• Supports prerelease versions (alpha, beta, rc, etc.)
• Supports dry-run mode for testing

start-next

Purpose: Prepare for the next development cycle by bumping patch versions

This command helps maintain a continuous development workflow by automatically incrementing patch versions immediately after a release:

• Bumps patch version in manifest files for each package
• Creates “chore” commits directly on the base branch
• Does NOT create pull requests or tags
• Skips packages that haven’t been tagged yet
• Supports filtering to specific packages with --packages flag
• Ensures version numbers are always ahead of the last release

Usage:

# Start next release cycle for all packages
releasaurus start-next \
  --forge github \
  --repo "https://github.com/owner/repo"

# Target specific packages only
releasaurus start-next \
  --forge github \
  --repo "https://github.com/owner/repo" \
  --packages pkg-a,pkg-b

# With custom base branch
releasaurus start-next \
  --forge github \
  --repo "https://github.com/owner/repo" \
  --base-branch develop

When to use:

• After merging a release PR and publishing a release
• To immediately bump versions for the next development cycle
• To keep manifest versions ahead of released versions

How it works:

1. Identifies all packages that have been previously tagged
2. Analyzes each package’s current version from its latest tag
3. Bumps the patch version (e.g., 1.2.3 → 1.2.4)
4. Updates manifest files (package.json, Cargo.toml, etc.)
5. Creates a chore commit directly on the base branch

Note: This command commits directly to your base branch without creating a pull request. Make sure you have the appropriate permissions and that your branch protection rules allow this operation.

show

Purpose: Query release information without making changes

This command provides release data for inspection, debugging, and custom automation:

• View projected next releases or retrieve existing release notes
• Useful for debugging configuration and troubleshooting version detection
• Generate custom notification scripts for pre/post-release workflows
• Supports writing output to files for processing

Sub-commands:

show next-release

Returns projected next release information as JSON:

# Get all projected releases
releasaurus show next-release \
  --forge github \
  --repo "https://github.com/owner/repo"

# Filter to specific package
releasaurus show next-release \
  --package my-pkg \
  --forge github \
  --repo "https://github.com/owner/repo"

# Write to file
releasaurus show next-release \
  --out-file releases.json \
  --forge github \
  --repo "https://github.com/owner/repo"

# Test locally
releasaurus show next-release --forge local --repo "."

Output: JSON array of releasable packages with version, commits, and notes.

show release

Retrieves release data for an existing tag, including the tag name, commit SHA, and release notes:

# Display release notes
releasaurus show release \
  --tag v1.0.0 \
  --forge github \
  --repo "https://github.com/owner/repo"

# Save to file
releasaurus show release \
  --tag v1.0.0 \
  --out-file release.json \
  --forge github \
  --repo "https://github.com/owner/repo"

Output: JSON object containing release data with fields:

• tag - The release tag name
• sha - The commit SHA the tag points to
• notes - The release notes content

Custom Notifications: Use these commands to build notification scripts that announce upcoming releases (pre-release) or published releases (post-release) to Slack, Discord, email, or other channels.

See Environment Variables for authentication setup.

Basic Usage Pattern

The typical Releasaurus workflow follows this pattern (can be run from any directory):

# Step 1: Create release preparation PR (run from anywhere)
releasaurus release-pr \
  --forge github \
  --repo "https://github.com/owner/repo"

# Step 2: Review and merge the PR (done via web interface)

# Step 3: Publish the release (run from anywhere)
releasaurus release \
  --forge github \
  --repo "https://github.com/owner/repo"

# Step 4 (Optional): Start next development cycle
releasaurus start-next \
  --forge github \
  --repo "https://github.com/owner/repo"

Note: These commands work by accessing your repository through the forge API, analyzing commits and files, creating branches with updates, and managing pull requests—all without requiring a local clone.

Global Options

All commands support these global options:

Platform Selection

Choose your Git forge platform using the --forge flag with a repository URL:

# GitHub
--forge github --repo "https://github.com/owner/repository"

# GitLab
--forge gitlab --repo "https://gitlab.com/group/project"

# Gitea (or Forgejo)
--forge gitea --repo "https://git.example.com/owner/repo"

# Local repository (for testing)
--forge local --repo "."

Available forge types:

• github - For github.com and GitHub Enterprise
• gitlab - For gitlab.com and self-hosted GitLab instances
• gitea - For gitea.com and self-hosted Gitea instances
• local - For testing against local repositories

Dry Run Mode

Test your release workflow without making any actual changes to your repository. Dry-run mode performs all analysis and validation steps while logging what actions would be taken, but prevents any modifications to your forge platform.

Note: Dry-run mode automatically enables debug logging for maximum visibility into what would happen.

What dry-run mode does:

• ✅ Analyzes commit history since the last release
• ✅ Determines version bumps based on conventional commits
• ✅ Generates changelog content
• ✅ Validates configuration and file formats
• ✅ Logs detailed information about what would be created/modified

What dry-run mode prevents:

• ❌ Creating or updating branches
• ❌ Creating or updating pull requests
• ❌ Creating Git tags
• ❌ Publishing releases
• ❌ Modifying repository labels

Usage:

# Via command line flag
releasaurus release-pr \
  --dry-run \
  --forge github \
  --repo "https://github.com/owner/repo"

releasaurus release \
  --dry-run \
  --forge github \
  --repo "https://github.com/owner/repo"

# Via environment variable
export RELEASAURUS_DRY_RUN=true
releasaurus release-pr \
  --forge github \
  --repo "https://github.com/owner/repo"

releasaurus release \
  --forge github \
  --repo "https://github.com/owner/repo"

Output: Dry-run mode produces detailed debug logs prefixed with dry_run: that show exactly what operations would be performed, including PR titles, version numbers, file changes, and release notes. Debug mode is automatically enabled to provide maximum visibility.

Local Repository Mode

Test your release workflow against a local repository without making any changes to remote forge platforms. Local repository mode is ideal for testing configuration changes before committing them.

Use case: Validate your releasaurus.toml configuration, version detection, and changelog generation against your local working directory before pushing changes to your remote forge.

What local repository mode does:

• ✅ Reads configuration and files from your local repository
• ✅ Analyzes local commit history and tags
• ✅ Determines version bumps based on local commits
• ✅ Generates changelog content from local history
• ✅ Validates configuration and file formats
• ✅ Logs what would be created (PRs, tags, releases)

What local repository mode prevents:

• ❌ Creating or updating remote branches
• ❌ Creating or updating pull requests on forge platforms
• ❌ Creating or pushing Git tags to remote
• ❌ Publishing releases to forge platforms
• ❌ Any modifications to remote repositories

Usage:

# Test from current directory
releasaurus release-pr --forge local --repo "."

# Test from specific path
releasaurus release-pr --forge local --repo "/path/to/your/repo"

# Works with release command too
releasaurus release --forge local --repo "."

Typical workflow:

# 1. Make changes to releasaurus.toml
vim releasaurus.toml

# 2. Test locally to verify configuration
releasaurus release-pr --forge local --repo "."

# 3. Review the logs to ensure everything looks correct

# 4. Commit your config changes
git add releasaurus.toml
git commit -m "chore: update release configuration"
git push

# 5. Run against remote forge
releasaurus release-pr \
  --forge github \
  --repo "https://github.com/owner/repo"

Note: Local repository mode operates on your working directory’s Git repository and does not require forge authentication tokens. See the Troubleshooting guide for help diagnosing configuration issues.

Configuration Overrides

Override configuration properties from the command line without modifying your releasaurus.toml file. This is useful for testing different settings, creating one-off releases with custom configurations, or using different values in CI/CD pipelines.

Available overrides:

• --base-branch <branch> - Override the base branch for the release
• --prerelease-suffix <suffix> - Set or override global prerelease suffix. This is applied to all packages
• --prerelease-strategy <strategy> - Set global prerelease strategy (versioned or static). This is applied to all packages
• --set-package <package_name>.<property>=<value> - Override package-specific properties. The takes precedence over all global overrides and config. Not all properties are overridable. If you try to set an unsupported property and error will be displayed with available valid values. Currently there is support for --set-package <pkg_name>.prerelease.suffix=<suffix> and --set-package <pkg_name>.prerelease.strategy=<strategy>

Override precedence (highest to lowest):

1. Package-specific CLI overrides (--set-package)
2. Global CLI overrides (--base-branch, --prerelease-*)
3. Package configuration in releasaurus.toml
4. Global configuration in releasaurus.toml
5. Default values

Usage examples:

# Override base branch
releasaurus release-pr \
  --base-branch develop \
  --forge github \
  --repo "https://github.com/owner/repo"

# Override global prerelease configuration
releasaurus release-pr \
  --prerelease-suffix beta \
  --prerelease-strategy versioned \
  --forge github \
  --repo "https://github.com/owner/repo"

# Override package-specific prerelease suffix
releasaurus release-pr \
  --set-package my-pkg.prerelease.suffix=rc \
  --forge github \
  --repo "https://github.com/owner/repo"

# Override package-specific prerelease strategy
releasaurus release-pr \
  --set-package my-pkg.prerelease.strategy=static \
  --forge github \
  --repo "https://github.com/owner/repo"

# Combine multiple overrides
releasaurus release-pr \
  --base-branch staging \
  --prerelease-suffix alpha \ # applies to all packages
  --set-package frontend.prerelease.suffix=beta \ # applies only to frontend
  --forge github \
  --repo "https://github.com/owner/repo"

Use cases:

• Test prerelease configurations without modifying your config file
• Create emergency releases from different branches
• Use different settings across environments / branches (dev/staging/prod)
• Override per-package settings for specific releases

See the Configuration guide for details on prerelease configuration.

Authentication

Provide access tokens for API authentication:

# Via command line
--token "your_token_here"

# Via environment variables (recommended)
export GITHUB_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxx"
export GITLAB_TOKEN="glpat_xxxxxxxxxxxxxxxxxxxx"
export GITEA_TOKEN="xxxxxxxxxxxxxxxxxx"

Releasaurus automatically selects the appropriate environment variable based on the --forge type:

• --forge github uses GITHUB_TOKEN
• --forge gitlab uses GITLAB_TOKEN
• --forge gitea uses GITEA_TOKEN
• --forge local requires no authentication

Debug Logging

Enable detailed logging for troubleshooting:

# Via command line flag
--debug

# Via environment variable
export RELEASAURUS_DEBUG=true

This provides verbose output including:

• Project detection logic
• File modification details
• API request/response information
• Git operations and status

Note: Debug mode is automatically enabled when using --dry-run or RELEASAURUS_DRY_RUN=true.

See the Environment Variables guide for more details on RELEASAURUS_DEBUG.

Prerelease Versions

Prerelease versions can be configured in your releasaurus.toml file:

# Global prerelease for all packages
[prerelease]
suffix = "alpha"
strategy = "versioned"

[[package]]
path = "."
release_type = "node"

Or configure per-package:

[[package]]
path = "./packages/stable"
release_type = "rust"
# No prerelease - stable releases

[[package]]
path = "./packages/experimental"
release_type = "rust"
prerelease = { suffix = "beta", strategy = "versioned" }  # Beta releases

The prerelease strategy can be one of “versioned” or “static”. A “versioned” strategy will result in a trailing version as part of the prerelease, e.g. -alpha.0, -alpha.1 .... A “static” strategy will only add a static prerelease suffix, e.g. -SNAPSHOT.

Prerelease Behavior:

• Starting: v1.0.0 → v1.1.0-alpha.1 (with feature commit and suffix = "alpha", strategy = "versioned")
• Continuing: v1.1.0-alpha.1 → v1.1.0-alpha.2 (same identifier in config)
• Switching: v1.0.0-alpha.3 → v1.1.0-beta.1 (change suffix = "beta" in config)
• Graduating: v1.0.0-alpha.5 → v1.0.0 (remove prerelease from config)

To change prerelease identifiers or graduate to stable, update your configuration file and create a new release PR.

See the Configuration guide for complete prerelease configuration details.

Platform-Specific Examples

GitHub

# With explicit token
releasaurus release-pr \
  --forge github \
  --repo "https://github.com/myorg/myproject" \
  --token "ghp_xxxxxxxxxxxxxxxxxxxx"

# With environment variable
export GITHUB_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxx"
releasaurus release-pr \
  --forge github \
  --repo "https://github.com/myorg/myproject"

GitLab

# GitLab.com
releasaurus release-pr \
  --forge gitlab \
  --repo "https://gitlab.com/mygroup/myproject" \
  --token "glpat_xxxxxxxxxxxxxxxxxxxx"

# Self-hosted GitLab
releasaurus release-pr \
  --forge gitlab \
  --repo "https://gitlab.company.com/team/project" \
  --token "glpat_xxxxxxxxxxxxxxxxxxxx"

Gitea

# Self-hosted Gitea
releasaurus release-pr \
  --forge gitea \
  --repo "https://git.company.com/team/project" \
  --token "xxxxxxxxxxxxxxxxxx"

# Works with Forgejo too
releasaurus release-pr \
  --forge gitea \
  --repo "https://forgejo.example.com/org/repo" \
  --token "xxxxxxxxxxxxxxxxxx"

Environment Variables

For security and convenience, use environment variables instead of command-line tokens. When environment variables are set, you can omit the --token flag.

See the Environment Variables guide for complete details on all available environment variables, authentication token setup, and configuration options.

Help and Documentation

Get help for any command:

# General help
releasaurus --help

# Command-specific help
releasaurus <cmd> --help

# Version information
releasaurus --version

Next Steps

For integration and automation:

• Troubleshooting - Common issues and solutions

CI/CD Integration

Releasaurus provides seamless integration with popular CI/CD platforms through official actions and components that automate your release workflow, eliminating the need to run Releasaurus commands manually.

Overview

All Releasaurus CI/CD integrations follow the same workflow:

1. Automatic Release PRs: When you push to your main branch, a release PR is automatically created (or updated) with version bumps and changelog
2. Review and Merge: Review the generated release PR and merge when ready
3. Automatic Publishing: After merge, the release is automatically tagged and published

This hands-off approach means you focus on writing code with conventional commits, and Releasaurus handles the rest.

GitHub Actions

Releasaurus provides official GitHub Actions that integrate directly with your GitHub repository workflows.

Available Actions

Three GitHub Actions are available:

• Workflow Action - Composite action that runs both release-pr and release (recommended for most users)
• Release PR Action - Creates and manages release pull requests
• Release Action - Publishes releases after PR merge

Quick Setup

Create .github/workflows/release.yml in your repository:

name: Release
on:
  workflow_dispatch:
  push:
    branches: [main]

jobs:
  release:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
    steps:
      - name: Release
        uses: robgonnella/releasaurus/action/github@vX.X.X
        with:
          token: ${{ secrets.GITHUB_TOKEN }}

For detailed input options and advanced usage, see the Workflow Action documentation for all available inputs and configuration options.

GitLab CI/CD

Releasaurus provides official GitLab CI components that integrate seamlessly with GitLab pipelines.

Available Components

Three GitLab CI components are available:

• Workflow Component - Composite component that includes both release-pr and release (recommended for most users)
• Release PR Component - Creates and manages release merge requests
• Release Component - Publishes releases after MR merge

Quick Setup

Create .gitlab-ci.yml in your repository:

include:
  - component: gitlab.com/rgon/releasaurus/workflow@vX.X.X
    inputs:
      token: $RELEASE_TOKEN

For detailed configuration options and advanced usage, see the Workflow Component documentation.

Gitea Actions

Releasaurus provides official Gitea Actions that integrate with Gitea Actions workflows.

Available Actions

Three Gitea Actions are available:

• Workflow Action - Composite action that runs both release-pr and release (recommended for most users)
• Release PR Action - Creates and manages release pull requests
• Release Action - Publishes releases after PR merge

Quick Setup

Create .gitea/workflows/release.yml in your repository:

name: Release
on:
  workflow_dispatch:
  push:
    branches: [main]

jobs:
  release:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
    steps:
      - name: Run Releasaurus
        uses: rgon/releasaurus/action/gitea@vX.X.X
        with:
          token: ${{ secrets.GITEA_TOKEN }}

For detailed input options and advanced usage, see the Workflow Action documentation.

Configuration

All CI/CD integrations work with your existing releasaurus.toml configuration file. No additional CI/CD-specific configuration is required.

If you need to customize the release workflow (e.g., skip certain commit types, use prerelease versions, handle monorepos), simply update your releasaurus.toml file. See the Configuration guide for all available options.

Benefits of CI/CD Integration

• Fully Automated: Push commits and releases happen automatically
• Consistent Process: Same release workflow across all your projects
• Safe Reviews: Release PRs/MRs provide review opportunities before publishing
• Zero Maintenance: No need to remember release commands or procedures
• Team Friendly: Anyone can trigger releases by merging the release PR/MR

Next Steps

• Review Configuration to customize your release process
• Check Commands for manual release options
• See Troubleshooting if you encounter issues

Troubleshooting

This guide helps you diagnose and resolve common issues when using Releasaurus. If you encounter problems not covered here, please check the GitHub issues or create a new one.

Common Issues

Configuring First Release Search Depth

The first_release_search_depth setting controls how many commits to analyze when no matching tags are found for a package’s configured prefix. The default is 400 commits.

When this setting applies:

This setting only affects the first release when Releasaurus cannot find any existing tags matching your package’s tag_prefix. Once a matching tag exists, Releasaurus will analyze all commits back to that tag, regardless of this setting.

What this setting does:

1. Limits first release analysis - Prevents analyzing thousands of commits when creating your very first release
2. Performance optimization - Improves speed for repositories with extensive commit history but no existing tags

When to adjust this setting:

Increase search depth

If you want more comprehensive changelogs for your first release:

# Analyze more commits for first release
first_release_search_depth = 1000

[[package]]
path = "."

Use case: You want your first release changelog to include more commit history.

Decrease search depth

For faster first release creation:

# Search fewer commits for better performance
first_release_search_depth = 100

[[package]]
path = "."

Use case: You want faster first release creation and don’t need extensive commit history in the initial changelog.

Note: This setting does NOT affect tag discovery. Releasaurus searches all tags regardless of this setting. This only limits how many commits are analyzed when no matching tags exist.

Issue: Releasaurus doesn’t find existing tags

Possible causes:

1. Tag prefix mismatch - Your configured tag_prefix doesn’t match existing tags
2. Tags don’t follow semver - Existing tags don’t use semantic versioning format

Solutions:

Match your tag prefix:

[[package]]
path = "."
tag_prefix = "v"  # Must match your existing tags like "v1.0.0"

Common prefix patterns:

• tag_prefix = "v" for tags like v1.0.0, v2.1.0
• tag_prefix = "api-v" for tags like api-v1.0.0
• tag_prefix = "" for tags like 1.0.0 (no prefix)

Authentication Issues

Issue: “Authentication failed” or “401 Unauthorized”

Symptoms:

• Cannot access repository
• API calls fail with authentication errors
• Permission denied messages

Solutions:

1. Verify token is set:

   # Check environment variable
   echo $GITHUB_TOKEN
   echo $GITLAB_TOKEN
   echo $GITEA_TOKEN
   
   # Or provide via command line
   releasaurus release-pr \
     --forge github \
     --repo "https://github.com/owner/repo" \
     --token "your_token"
   

2. Check token scopes - Ensure your token has required permissions (see Environment Variables)

3. Token expiration - Generate a new token if the current one has expired

Issue: “Repository not found” with valid repository

Cause: Token doesn’t have access to the repository or repository URL is incorrect.

Solutions:

1. Verify repository URL:

   # Correct format examples
   --forge github --repo "https://github.com/owner/repository"
   --forge gitlab --repo "https://gitlab.com/group/project"
   --forge gitea --repo "https://gitea.example.com/owner/repo"
   

2. Check repository access - Ensure your token’s associated account has appropriate permissions.

3. Test with local mode first:

   # Clone the repository and test locally
   git clone https://github.com/owner/repo
   cd repo
   releasaurus show next-release --forge local --repo "."
   

Inspecting Projected Releases

Use the show next-release command to inspect what Releasaurus will do before creating a PR or making any changes:

# See all projected releases
releasaurus show next-release \
  --forge github \
  --repo "https://github.com/owner/repo"

# Inspect specific package
releasaurus show next-release \
  --package my-pkg \
  --forge github \
  --repo "https://github.com/owner/repo"

# Save output to file for detailed inspection
releasaurus show next-release \
  --out-file releases.json \
  --forge github \
  --repo "https://github.com/owner/repo"

# Test locally without authentication
releasaurus show next-release --forge local --repo "."

Use this command to:

• Verify version calculation - Check if the next version matches your expectations
• Inspect commit analysis - See which commits are included and how they’re categorized
• Validate configuration - Ensure releasaurus.toml settings produce desired results
• Preview release notes - Review changelog content before creating a PR
• Debug tag matching - Verify tag prefix configuration matches repository tags
• Test monorepo setup - Confirm package detection and independent versioning

The JSON output includes all information that would be used in a release PR, making it ideal for diagnosing issues without modifying your repository.

Debug Mode

When troubleshooting any issue, enable debug mode for detailed information:

# Via command line flag
releasaurus release-pr \
  --debug \
  --forge github \
  --repo "https://github.com/owner/repo"

# Or via environment variable
export RELEASAURUS_DEBUG=true
releasaurus release-pr \
  --forge github \
  --repo "https://github.com/owner/repo"

Debug output includes:

• Commit analysis and categorization
• Version calculation logic
• File detection and modification details
• API requests and responses
• Tag matching and selection

See the Environment Variables guide for more details on RELEASAURUS_DEBUG.

Dry Run Mode

Before making changes to your repository, use dry-run mode to safely test and diagnose issues:

# Via command line flag
releasaurus release-pr \
  --dry-run \
  --forge github \
  --repo "https://github.com/owner/repo"

# Via environment variable
export RELEASAURUS_DRY_RUN=true
releasaurus release-pr \
  --forge github \
  --repo "https://github.com/owner/repo"

Note: Dry-run mode automatically enables debug logging for maximum visibility.

See the Commands guide for complete details.

Local Repository Mode

Test your configuration and diagnose issues against your local repository without requiring authentication or making remote changes:

# Test from current directory
releasaurus release-pr --forge local --repo "."

# Test from specific path
releasaurus release-pr --forge local --repo "/path/to/your/repo"

Use local repository mode for:

• Configuration validation - Test releasaurus.toml changes before committing
• Version detection issues - Verify tag prefix matching and version calculation
• Changelog preview - See what changelog would be generated from local commits
• Quick diagnostics - Test without authentication setup or network access

See the Commands guide for complete details.

Getting Help

If you’re still experiencing issues:

1. Check existing issues: GitHub Issues
2. Create a new issue with:
   • Debug output (remove sensitive information)
   • Repository type and structure
   • Command used
   • Expected vs actual behavior
3. Include environment details:
   • Operating system
   • Releasaurus version (releasaurus --version)
   • Forge platform and hosting type (e.g., GitHub.com, self-hosted GitLab)

Supported Languages & Frameworks

Releasaurus provides native support for multiple programming languages. Configure your project’s release_type in releasaurus.toml, and Releasaurus automatically updates all relevant version files.

Quick Configuration

[[package]]
path = "."
release_type = "node"  # or rust, python, java, php, ruby, generic

Language Support Reference

Notes

• Workspaces/Monorepos: All languages support workspace configurations with multiple packages
• Lock files: Automatically updated when present
• Generic projects: Use additional_manifest_files to specify custom version file patterns. See Configuration for details.

Next Steps

For complete configuration options including monorepo setup, changelog customization, and prerelease versions, see the Configuration guide.

Configuration

Releasaurus works out-of-the-box with zero configuration, but provides extensive customization through an optional releasaurus.toml file.

Do You Need Configuration?

You DON’T need configuration if:

• You only need changelog generation and tagging (no version file updates)
• You’re happy with the default changelog format
• You’re happy with the default tag prefix “v” (e.g., v1.0.0)

You DO need configuration if:

• You want version file updates (requires specifying release_type)
• You want custom changelog templates or formatting
• You have multiple packages in one repository (monorepo)
• You want custom prefixed tags (e.g., cli-v1.0.0)

Quick Start Examples

Single Package with Version Updates

The most common setup:

# releasaurus.toml
[[package]]
path = "."
release_type = "node"  # or rust, python, java, php, ruby

Multi-Package (Monorepo)

Multiple independently-versioned packages:

[[package]]
path = "./frontend"
release_type = "node"
tag_prefix = "frontend-v"

[[package]]
path = "./backend"
release_type = "rust"
tag_prefix = "backend-v"

See Monorepo Configuration for complete details.

Prerelease Versions

Create alpha/beta releases:

[prerelease]
suffix = "alpha"
strategy = "versioned"  # or "static"

[[package]]
path = "."
release_type = "node"

This creates versions like v1.0.0-alpha.1, v1.0.0-alpha.2, etc.

See Prerelease Configuration for complete details.

Custom Changelog

Filter commits and customize formatting:

[changelog]
skip_ci = true
skip_chore = true
skip_miscellaneous = true

[[package]]
path = "."
release_type = "rust"

See Changelog Configuration for template customization and complete options.

Configuration Topics

Core Settings

• Prerelease Versions - Alpha, beta, RC releases with versioned or static strategies
• Changelog Customization - Filter commits, customize templates, format output
• Monorepo Setup - Multiple packages, separate PRs, independent versioning

Reference

• Configuration Reference - Complete list of all configuration options with descriptions

Configuration File Location

Place releasaurus.toml in your project’s root directory:

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

Command-Line Overrides

Many configuration options can be overridden from the command line without modifying your config file. This is useful for testing different settings or using different values in CI/CD pipelines.

See Configuration Overrides in the Commands guide for details.

Testing Your Configuration

Test your configuration locally without making remote changes:

# Test against your local repository
releasaurus release-pr --forge local --repo "."

# Review the output to verify settings
# Then run against your remote forge when ready

See Local Repository Mode for complete details.

Next Steps

• Getting started? See Quick Start for a 2-minute tutorial
• Need help? Check Troubleshooting for common issues
• CI/CD? See CI/CD Integration for automation

Prerelease Configuration

Create alpha, beta, RC, or snapshot releases with automatic version management.

Overview

Prerelease versions allow you to publish test releases before final stable versions. Releasaurus supports two strategies:

• Versioned: Incremental counters (e.g., 1.0.0-alpha.1, 1.0.0-alpha.2)
• Static: Fixed suffix (e.g., 1.0.0-SNAPSHOT, 1.1.0-SNAPSHOT)

Quick Configuration

Global Prerelease (All Packages)

[prerelease]
suffix = "alpha"
strategy = "versioned"  # or "static"

[[package]]
path = "."
release_type = "node"

Per-Package Override

[prerelease]
suffix = "beta"
strategy = "versioned"

[[package]]
path = "./stable"
release_type = "rust"
# Uses global beta prerelease

[[package]]
path = "./experimental"
release_type = "rust"
prerelease = { suffix = "alpha", strategy = "versioned" }
# Override with alpha

Configuration Options

suffix

The identifier to append to version numbers.

Common values:

• "alpha" - Early testing phase
• "beta" - Feature complete, testing phase
• "rc" - Release candidate
• "preview" - Preview releases
• "dev" - Development/nightly builds
• "SNAPSHOT" - Java snapshot versioning

Omit or set to empty string to disable prereleases.

strategy

Controls how version numbers are generated.

Options:

• "versioned" (default) - Adds incremental counter (.1, .2, .3)
• "static" - Uses suffix as-is without counter

Versioned Strategy

Incremental counters track iteration within a prerelease series.

Starting a Prerelease

Current:  v1.0.0
Commit:   feat: new feature
Config:   suffix = "alpha", strategy = "versioned"
Result:   v1.1.0-alpha.1

Continuing with Same Identifier

Current:  v1.1.0-alpha.1
Commit:   fix: bug fix
Config:   suffix = "alpha", strategy = "versioned"
Result:   v1.1.0-alpha.2

Switching Identifier

Current:  v1.0.0-alpha.3
Commit:   feat: new feature
Config:   suffix = "beta", strategy = "versioned"
Result:   v1.1.0-beta.1

Switching identifiers recalculates the base version and resets the counter.

Graduating to Stable

Current:  v1.0.0-alpha.5
Commit:   fix: final fix
Config:   (no prerelease section)
Result:   v1.0.0

Remove the [prerelease] section or set suffix = "" to graduate.

Static Strategy

Fixed suffix without counters, common in Java ecosystems.

Starting a Prerelease

Current:  v1.0.0
Commit:   fix: bug fix
Config:   suffix = "SNAPSHOT", strategy = "static"
Result:   v1.0.1-SNAPSHOT

Continuing with Same Identifier

Current:  v1.0.1-SNAPSHOT
Commit:   feat: new feature
Config:   suffix = "SNAPSHOT", strategy = "static"
Result:   v1.1.0-SNAPSHOT

Version number updates based on commit type, suffix stays constant.

Graduating to Stable

Current:  v1.0.1-SNAPSHOT
Commit:   fix: final fix
Config:   (no prerelease section)
Result:   v1.0.1

Practical Examples

Monorepo with Mixed Prerelease States

# Most packages stable, some experimental
separate_pull_requests = true

[[package]]
path = "./core"
release_type = "rust"
tag_prefix = "core-v"
# No prerelease - stable only

[[package]]
path = "./experimental"
release_type = "rust"
tag_prefix = "exp-v"
prerelease = { suffix = "alpha", strategy = "versioned" }

[[package]]
path = "./staging"
release_type = "node"
tag_prefix = "staging-v"
prerelease = { suffix = "beta", strategy = "versioned" }

Java Project with Snapshots

[prerelease]
suffix = "SNAPSHOT"
strategy = "static"

[[package]]
path = "."
release_type = "java"

Progressive Release Pipeline

# Start in alpha, progress to beta, then stable
[[package]]
path = "."
release_type = "node"

# Phase 1: Configure alpha
# prerelease = { suffix = "alpha", strategy = "versioned" }

# Phase 2: Switch to beta when ready
# prerelease = { suffix = "beta", strategy = "versioned" }

# Phase 3: Remove prerelease for stable release

Command-Line Overrides

Override prerelease settings without modifying your config file:

# Test beta prereleases
releasaurus release-pr \
  --prerelease-suffix beta \
  --prerelease-strategy versioned \
  --forge github \
  --repo "https://github.com/org/repo"

# Override specific package
releasaurus release-pr \
  --set-package my-pkg.prerelease.suffix=rc \
  --set-package my-pkg.prerelease.strategy=versioned \
  --forge github \
  --repo "https://github.com/org/repo"

# Disable prerelease temporarily
releasaurus release-pr \
  --prerelease-suffix "" \
  --forge github \
  --repo "https://github.com/org/repo"

See Configuration Overrides for complete details.

Configuration Priority

Settings are applied in this order (highest to lowest):

1. Package-specific CLI overrides (--set-package)
2. Global CLI overrides (--prerelease-suffix, --prerelease-strategy)
3. Package prerelease configuration in releasaurus.toml
4. Global [prerelease] configuration in releasaurus.toml
5. No prerelease (stable versions)

Testing Prerelease Configuration

Test your prerelease settings locally:

# See what version would be generated
releasaurus release-pr --forge local --repo "."

# With command-line overrides
releasaurus release-pr \
  --prerelease-suffix beta \
  --forge local \
  --repo "."

Next Steps

• Configuration Overview - Main configuration guide
• Configuration Overrides - CLI override details
• Quick Start - Get started in 2 minutes

Changelog Configuration

Customize changelog generation, filter commits, and format output with Tera templates.

Overview

Releasaurus automatically generates changelogs from commit history using conventional commits. Customize what’s included and how it’s formatted through the [changelog] section.

Quick Configuration

Filter Out Noise

Exclude CI, chore, and non-conventional commits:

[changelog]
skip_ci = true
skip_chore = true
skip_miscellaneous = true

[[package]]
path = "."
release_type = "node"

Include Author Names

Show who made each commit:

[changelog]
include_author = true

[[package]]
path = "."
release_type = "rust"

Commit Filtering Options

skip_ci (default: false)

Exclude CI/CD related commits:

[changelog]
skip_ci = true  # Excludes "ci: update workflow"

skip_chore (default: false)

Exclude chore commits:

[changelog]
skip_chore = true  # Excludes "chore: update deps"

skip_miscellaneous (default: false)

Exclude non-conventional commits:

[changelog]
skip_miscellaneous = true  # Excludes commits without type prefix

skip_merge_commits (default: true)

Exclude merge commits:

[changelog]
skip_merge_commits = false  # Include "Merge pull request #123"

skip_release_commits (default: true)

Exclude release commits created by Releasaurus:

[changelog]
skip_release_commits = false  # Include "chore(main): release v1.0.0"

include_author (default: false)

Include commit author names in changelog entries:

[changelog]
include_author = true

Template Customization

body Template

The main changelog content template using Tera syntax.

Default template creates entries starting with # [version](link) - date.

Custom template example:

[changelog]
body = """## Release v{{ version }}

Released on {{ timestamp | date(format="%Y-%m-%d") }}

{% for group, commits in commits | group_by(attribute="group") %}
### {{ group }}
{% for commit in commits %}
- {{ commit.message }} ({{ commit.short_id }})
{% endfor %}
{% endfor %}"""

Template Variables

Available in the body template:

Release Variables

• version - Semantic version string (e.g., “1.2.3”)
• link - URL to the release
• sha - Git commit SHA
• timestamp - Unix timestamp
• include_author - Boolean flag for author names

Commit Variables

The commits array contains objects with:

• id - Full commit SHA
• short_id - Abbreviated SHA
• group - Category (Features, Bug Fixes, etc.)
• scope - Optional scope from conventional commit
• title - Commit message without type/scope
• body - Optional extended description
• link - URL to the commit
• breaking - Boolean for breaking changes
• breaking_description - Breaking change details
• merge_commit - Boolean for merge commits
• timestamp - Commit timestamp
• author_name - Commit author name
• author_email - Author email
• raw_title - Original unprocessed title
• raw_message - Original full message

Practical Examples

Clean User-Facing Changelog

Focus only on features and fixes:

[changelog]
skip_ci = true
skip_chore = true
skip_miscellaneous = true
skip_merge_commits = true
skip_release_commits = true

[[package]]
path = "."
release_type = "node"

Comprehensive Changelog

Include everything except merges:

[changelog]
skip_ci = false
skip_chore = false
skip_miscellaneous = false
skip_merge_commits = true
include_author = true

[[package]]
path = "."
release_type = "rust"

Custom Template with Authors

[changelog]
include_author = true
body = """# {{ version }} - {{ timestamp | date(format="%Y-%m-%d") }}

{% for group, commits in commits | group_by(attribute="group") %}
## {{ group }}
{% for commit in commits %}
- {{ commit.title }}{% if include_author %} by {{
commit.author_name }}{% endif %}
{% endfor %}
{% endfor %}"""

[[package]]
path = "."
release_type = "python"

Template Tips

Conditional Author Display

{% if include_author %} <{{ commit.author_name }}>{% endif %}

Filter Merge Commits

{% for commit in commits | filter(attribute="merge_commit",
value=false) %}

Group by Category

{% for group, commits in commits | group_by(attribute="group") %}
### {{ group }}
{% endfor %}

Highlight Breaking Changes

{% if commit.breaking %}
**BREAKING**: {{ commit.message }}
{% if commit.breaking_description %}
> {{ commit.breaking_description }}
{% endif %}
{% endif %}

Testing Templates

Test your template locally before committing changes:

# See generated changelog with your template
releasaurus release-pr --forge local --repo "."

Review the output to verify formatting looks correct.

Tera Template Resources

Releasaurus uses the Tera templating engine. See the Tera documentation for advanced filtering and formatting options.

Next Steps

• Configuration Overview - Main configuration guide
• Prerelease Configuration - Alpha/beta releases
• Configuration Reference - All options

Monorepo Configuration

Manage multiple independently-versioned packages within a single repository.

Overview

Releasaurus supports monorepos with:

• Multiple packages with independent versions
• Separate or combined pull requests
• Custom tag prefixes per package
• Per-package configuration overrides

Quick Configuration

Basic Monorepo (Combined Releases)

All packages released together in one PR:

[[package]]
path = "./frontend"
release_type = "node"
tag_prefix = "frontend-v"

[[package]]
path = "./backend"
release_type = "rust"
tag_prefix = "backend-v"

Tags: frontend-v1.0.0, backend-v2.3.0

Independent Releases (Separate PRs)

Each package gets its own PR:

separate_pull_requests = true

[[package]]
path = "./frontend"
release_type = "node"
tag_prefix = "frontend-v"

[[package]]
path = "./backend"
release_type = "rust"
tag_prefix = "backend-v"

Creates separate PRs like:

• releasaurus-release-main-frontend
• releasaurus-release-main-backend

Configuration Options

separate_pull_requests (default: false)

Control PR creation strategy:

separate_pull_requests = true  # or false

false (default) - Single PR for all packages true - Separate PR for each package with changes

Package Configuration

Each package needs:

• path - Directory relative to repository root
• release_type - Language/framework (rust, node, python, etc.)
• tag_prefix (optional) - Custom tag prefix

Tag prefix defaults:

• Root packages (path = ".") → "v"
• Nested packages → "<package-name>-v"

When to Use Each Strategy

Single PR Mode (Default)

Best for:

• Tightly coupled packages that always release together
• Small monorepos (2-5 packages)
• Teams that prefer coordinated releases
• Simple review workflow

Benefits:

• One review process
• Atomic releases
• Simpler workflow

Separate PR Mode

Best for:

• Large monorepos (5+ packages)
• Independently versioned packages
• Different teams owning different packages
• Different release cadences per package

Benefits:

• Independent release cycles
• Parallel reviews
• Flexible scheduling

Practical Examples

Frontend + Backend + Shared Library

separate_pull_requests = true

[[package]]
path = "./apps/web"
release_type = "node"
tag_prefix = "web-v"

[[package]]
path = "./apps/api"
release_type = "rust"
tag_prefix = "api-v"

[[package]]
path = "./packages/shared"
release_type = "python"
tag_prefix = "shared-v"

Microservices Repository

separate_pull_requests = true

[[package]]
path = "./services/auth"
release_type = "node"
tag_prefix = "auth-v"

[[package]]
path = "./services/payments"
release_type = "node"
tag_prefix = "payments-v"

[[package]]
path = "./services/notifications"
release_type = "python"
tag_prefix = "notifications-v"

[[package]]
path = "./services/analytics"
release_type = "rust"
tag_prefix = "analytics-v"

Workspace in Subdirectory

For workspaces not at repository root:

[[package]]
name = "api-server"
workspace_root = "backend"
path = "services/api"
release_type = "rust"
tag_prefix = "api-v"

[[package]]
name = "worker"
workspace_root = "backend"
path = "services/worker"
release_type = "rust"
tag_prefix = "worker-v"

This updates:

• backend/services/api/Cargo.toml
• backend/services/worker/Cargo.toml
• backend/Cargo.lock (workspace lock file)

Mixed Prerelease States

Some packages stable, others in beta:

separate_pull_requests = true

[[package]]
path = "./stable-api"
release_type = "rust"
tag_prefix = "api-v"
# No prerelease - stable only

[[package]]
path = "./experimental-features"
release_type = "rust"
tag_prefix = "exp-v"
prerelease = { suffix = "beta", strategy = "versioned" }

Shared Code Patterns

Packages with Shared Dependencies

Use additional_paths to track shared code:

[[package]]
path = "./apps/web"
release_type = "node"
tag_prefix = "web-v"
additional_paths = ["shared/types", "shared/utils"]

[[package]]
path = "./apps/mobile"
release_type = "node"
tag_prefix = "mobile-v"
additional_paths = ["shared/types", "shared/utils"]

Both packages release when changes occur in shared/*.

Dedicated Shared Package

[[package]]
path = "./shared"
release_type = "node"
tag_prefix = "shared-v"

[[package]]
path = "./apps/web"
release_type = "node"
tag_prefix = "web-v"

[[package]]
path = "./apps/mobile"
release_type = "node"
tag_prefix = "mobile-v"

The shared package releases independently.

Workflow Differences

Single PR Workflow

1. Run releasaurus release-pr
2. One PR created with all package updates
3. Review and merge
4. Run releasaurus release
5. All packages tagged and released

Separate PR Workflow

1. Run releasaurus release-pr
2. Multiple PRs created (one per package with changes)
3. Review and merge each PR independently
4. Run releasaurus release after each merge
5. Each package tagged and released separately

Auto Start Next

Automatically bump versions after release:

auto_start_next = true

[[package]]
path = "./api"
release_type = "rust"
auto_start_next = false  # Override for this package

[[package]]
path = "./web"
release_type = "node"
# Uses global setting (true)

See start-next command for details.

Testing Monorepo Configuration

Test locally to verify package detection and tagging:

# See what packages would be released
releasaurus release-pr --forge local --repo "."

# Check:
# - All packages detected correctly
# - Tag prefixes match expectations
# - Separate/combined PR strategy works

Next Steps

• Configuration Overview - Main configuration guide
• Prerelease Configuration - Per- package prereleases
• Commands - All command options

Configuration Reference

Complete reference of all configuration options for releasaurus.toml.

Global Settings

base_branch

Type: String (optional)

Default: Repository’s default branch

Base branch to target for release PRs, tagging, and releases.

base_branch = "main"

Override: --base-branch CLI flag

first_release_search_depth

Type: Integer (optional)

Default: 400

Number of commits to analyze for the first release (when no tags exist).

first_release_search_depth = 400

When to adjust:

• Large repos: decrease to 100-200 for faster analysis
• Need more history: increase to 1000+
• CI/CD: use smaller values for speed

separate_pull_requests

Type: Boolean (optional)

Default: false

Create separate PRs for each package (true) or one combined PR (false).

separate_pull_requests = true

See Monorepo Configuration for details.

auto_start_next

Type: Boolean (optional)

Default: false

Automatically bump patch versions after publishing a release.

auto_start_next = true

Package-level settings override global. See start-next command.

breaking_always_increment_major

Type: Boolean (optional)

Default: true

Breaking changes (feat!: or BREAKING CHANGE:) increment major version.

breaking_always_increment_major = false

features_always_increment_minor

Type: Boolean (optional)

Default: true

Feature commits (feat:) increment minor version.

features_always_increment_minor = false

custom_major_increment_regex

Type: String (optional)

Default: None

Custom regex pattern to trigger major version bumps (additive with breaking changes).

custom_major_increment_regex = "MAJOR"

custom_minor_increment_regex

Type: String (optional)

Default: None

Custom regex pattern to trigger minor version bumps (additive with feat: commits).

custom_minor_increment_regex = "FEATURE"

Prerelease Section

[prerelease]

Global prerelease configuration for all packages.

suffix

Type: String (optional)

Default: None (stable releases)

Prerelease identifier (e.g., “alpha”, “beta”, “rc”, “SNAPSHOT”).

[prerelease]
suffix = "alpha"

Override: --prerelease-suffix CLI flag

strategy

Type: String (optional)

Default: “versioned”

Prerelease versioning strategy:

• "versioned" - Adds incremental counter (.1, .2)
• "static" - Uses suffix as-is

[prerelease]
suffix = "beta"
strategy = "versioned"

Override: --prerelease-strategy CLI flag

See Prerelease Configuration for complete details.

Changelog Section

[changelog]

Customize changelog generation and formatting.

skip_ci

Type: Boolean (optional)

Default: false

Exclude CI/CD commits from changelog.

[changelog]
skip_ci = true

skip_chore

Type: Boolean (optional)

Default: false

Exclude chore commits from changelog.

[changelog]
skip_chore = true

skip_miscellaneous

Type: Boolean (optional)

Default: false

Exclude non-conventional commits from changelog.

[changelog]
skip_miscellaneous = true

skip_merge_commits

Type: Boolean (optional)

Default: true

Exclude merge commits from changelog.

[changelog]
skip_merge_commits = false

skip_release_commits

Type: Boolean (optional)

Default: true

Exclude release commits created by Releasaurus.

[changelog]
skip_release_commits = false

include_author

Type: Boolean (optional)

Default: false

Include commit author names in changelog.

[changelog]
include_author = true

body

Type: String (optional)

Default: Standard template

Tera template for changelog body. See Changelog Configuration for template variables.

[changelog]
body = """## Release {{ version }}
..."""

Package Section

[[package]]

Define packages in your repository. Can have multiple.

path

Type: String (required)

Default: None

Directory path to the package, relative to workspace_root.

[[package]]
path = "."

workspace_root

Type: String (optional)

Default: “.”

Workspace root directory, relative to repository root.

[[package]]
workspace_root = "backend"
path = "services/api"

name

Type: String (optional)

Default: Derived from path

Explicit package name. If not set, derived from directory name.

[[package]]
name = "my-custom-name"
path = "packages/backend"

release_type

Type: String (required for version updates)

Default: None

Language/framework for version file updates:

• "rust" - Cargo.toml, Cargo.lock
• "node" - package.json, lock files
• "python" - pyproject.toml, setup.py, setup.cfg
• "java" - pom.xml, build.gradle
• "php" - composer.json
• "ruby" - .gemspec, Gemfile
• "generic" - Changelog/tagging only

[[package]]
path = "."
release_type = "node"

tag_prefix

Type: String (optional)

Default: Derived from package name

Git tag prefix. Defaults:

• Root packages: "v"
• Nested packages: "<name>-v"

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

auto_start_next

Type: Boolean (optional)

Default: Inherits global setting

Override global auto_start_next for this package.

[[package]]
path = "."
release_type = "node"
auto_start_next = false

prerelease

Type: Inline table (optional)

Default: Inherits global prerelease

Override global prerelease configuration.

[[package]]
path = "."
release_type = "rust"
prerelease = { suffix = "beta", strategy = "versioned" }

Override: --set-package <name>.prerelease.suffix=<value> CLI flag

additional_paths

Type: Array of strings (optional)

Default: None

Additional directories to monitor for changes.

[[package]]
path = "packages/api"
release_type = "node"
additional_paths = ["shared/utils", "shared/types"]

additional_manifest_files

Type: Array of strings (optional)

Default: None

Additional files to receive generic version updates.

[[package]]
path = "."
release_type = "rust"
additional_manifest_files = ["VERSION", "README.md"]

Files updated with regex pattern matching version = "x.y.z".

breaking_always_increment_major

Type: Boolean (optional)

Default: Inherits global setting

Override global breaking change behavior.

[[package]]
path = "."
release_type = "node"
breaking_always_increment_major = false

features_always_increment_minor

Type: Boolean (optional)

Default: Inherits global setting

Override global feature commit behavior.

[[package]]
path = "."
release_type = "rust"
features_always_increment_minor = false

custom_major_increment_regex

Type: String (optional)

Default: Inherits global setting

Override global major version regex.

[[package]]
path = "."
release_type = "node"
custom_major_increment_regex = "\\[BREAKING\\]"

custom_minor_increment_regex

Type: String (optional)

Default: Inherits global setting

Override global minor version regex.

[[package]]
path = "."
release_type = "rust"
custom_minor_increment_regex = "\\[FEATURE\\]"

Complete Example

# Global settings
base_branch = "main"
first_release_search_depth = 400
separate_pull_requests = false
auto_start_next = false
breaking_always_increment_major = true
features_always_increment_minor = true

# Global prerelease
[prerelease]
suffix = "beta"
strategy = "versioned"

# Changelog customization
[changelog]
skip_ci = true
skip_chore = true
skip_miscellaneous = false
include_author = false

# Package definitions
[[package]]
name = "frontend"
path = "./apps/web"
release_type = "node"
tag_prefix = "web-v"

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

Next Steps

• Configuration Overview - Getting started guide
• Prerelease Configuration - Detailed prerelease guide
• Changelog Configuration - Template customization
• Monorepo Configuration - Multi-package setup

Environment Variables

Environment variables provide a secure and flexible way to configure Releasaurus without hardcoding sensitive information or platform-specific settings. This reference covers all supported environment variables and their usage patterns.

Authentication Tokens

Primary Token Variables

GITHUB_TOKEN

Purpose: Authentication token for GitHub API access

Token Types:

Releasaurus supports both classic and fine-grained personal access tokens.

Classic Personal Access Token - Required Scopes:

• repo (full control of private repositories)
  • Includes: repo:status, repo_deployment, public_repo, repo:invite, security_events

Fine-Grained Personal Access Token - Required Permissions:

• Contents: Read and write access (for reading/updating files and creating commits)
• Issues: Read and write access (for managing PR labels)
• Pull requests: Read and write access (for creating and updating release PRs)

Fine-Grained Personal Access Token - Optional Permissions:

The following permissions may be needed depending on your workflow configuration:

• Actions: Read and write access (if using the GitHub Action and need to trigger workflow runs)
• Workflows: Read and write access (if using the GitHub Action and need to modify workflows)

Example:

export GITHUB_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxx"

Usage:

# With environment variable set
releasaurus release-pr \
  --forge github \
  --repo "https://github.com/owner/repo"

# Without environment variable (less secure)
releasaurus release-pr \
  --forge github \
  --repo "https://github.com/owner/repo" \
  --token "ghp_xxxxxxxxxxxxxxxxxxxx"

GITLAB_TOKEN

Purpose: Authentication token for GitLab API access

Required Scopes:

• api (full API access)
• read_repository (repository read access)
• write_repository (repository write access)

Token Types:

• Personal Access Tokens

Example:

export GITLAB_TOKEN="glpat_xxxxxxxxxxxxxxxxxxxx"

Usage:

# GitLab.com
releasaurus release-pr \
  --forge gitlab \
  --repo "https://gitlab.com/group/project"

# Self-hosted GitLab
releasaurus release-pr \
  --forge gitlab \
  --repo "https://gitlab.company.com/team/repo"

GITEA_TOKEN

Purpose: Authentication token for Gitea/Forgejo API access

Required Permissions:

• Repository read/write access
• Issue/PR management permissions

Example:

export GITEA_TOKEN="xxxxxxxxxxxxxxxxxx"

Usage:

# Self-hosted Gitea
releasaurus release-pr \
  --forge gitea \
  --repo "https://git.company.com/org/repo"

# Forgejo instance
releasaurus release-pr \
  --forge gitea \
  --repo "https://forgejo.example.com/user/project"

Token Selection: Releasaurus automatically selects the appropriate environment variable based on the --forge flag. Use --token to override or when the environment variable is not set.

Debug Configuration

RELEASAURUS_DEBUG

Purpose: Enable detailed debug logging for troubleshooting

Values:

• Any value (including true, false, 1, 0, etc.) - Enable debug mode
• Unset or empty - Disable debug mode (default)

Example:

export RELEASAURUS_DEBUG=true

Usage:

# Enable debug mode via environment variable
export RELEASAURUS_DEBUG=true
releasaurus release-pr \
  --forge github \
  --repo "https://github.com/owner/repo"

# Alternative: use the --debug flag
releasaurus release-pr \
  --debug \
  --forge github \
  --repo "https://github.com/owner/repo"

Note: Debug mode is enabled whenever RELEASAURUS_DEBUG is set to any value. To disable debug mode, the variable must be unset or empty. The --debug flag will always enable debug mode regardless of the environment variable value.

RELEASAURUS_DRY_RUN

Purpose: Enable dry-run mode to test release workflows without making actual changes

Values:

• Any value (including true, false, 1, 0, etc.) - Enable dry-run mode
• Unset or empty - Disable dry-run mode (default)

Behavior:

• Performs all analysis and validation steps
• Logs detailed information about what would happen
• Prevents any modifications to your forge platform (branches, PRs, tags, releases)
• Automatically enables debug mode for maximum visibility

Example:

export RELEASAURUS_DRY_RUN=true

Usage:

# Enable dry-run mode via environment variable
export RELEASAURUS_DRY_RUN=true
releasaurus release-pr \
  --forge github \
  --repo "https://github.com/owner/repo"

releasaurus release \
  --forge github \
  --repo "https://github.com/owner/repo"

# Alternative: use the --dry-run flag
releasaurus release-pr \
  --dry-run \
  --forge github \
  --repo "https://github.com/owner/repo"

Output: Produces detailed debug logs prefixed with dry_run: showing exactly what operations would be performed, including PR titles, version numbers, file changes, and release notes.

Note: Dry-run mode automatically enables debug logging regardless of the RELEASAURUS_DEBUG setting. This ensures you have maximum visibility into what would happen during the release process.

Next Steps

• Commands - Command-line options and usage patterns
• Configuration - Configuration file setup
• Troubleshooting - Resolving environment issues

Contributing

We appreciate your interest in contributing to Releasaurus! This guide will help you get started with contributing to the project, whether you’re fixing bugs, adding features, improving documentation, or helping with community support.

Ways to Contribute

🐛 Bug Reports

• Report bugs and issues you encounter
• Provide detailed reproduction steps
• Share your environment details

💡 Feature Requests

• Suggest new language/framework support
• Propose workflow improvements
• Request platform integrations

🔧 Code Contributions

• Fix bugs and implement features
• Add support for new languages
• Improve performance and reliability

📚 Documentation

• Improve existing documentation
• Add examples and tutorials
• Translate documentation

🎯 Testing

• Write and improve tests
• Test on different platforms
• Validate new features

💬 Community Support

• Help other users in discussions
• Answer questions in issues
• Share your experience and best practices

Development Environment Setup

Prerequisites

• Rust: 1.70 or higher (Install Rust)
• Git: For version control
• A supported platform: GitHub, GitLab, or Gitea account for testing

Getting Started

1. Fork and Clone

   # Fork the repository on GitHub
   git clone https://github.com/your-username/releasaurus.git
   cd releasaurus
   

2. Install Dependencies

   # Install Rust dependencies
   cargo build
   
   # Install development tools
   cargo install cargo-watch
   cargo install cargo-nextest  # Optional: faster test runner
   

3. Set Up Testing Environment

   # Create test tokens (with minimal permissions)
   export GITHUB_TOKEN="ghp_test_token_here"
   export GITLAB_TOKEN="glpat_test_token_here"
   export GITEA_TOKEN="test_token_here"
   
   # Run tests
   cargo test
   

4. Verify Installation

   # Build and test the binary
   cargo build --release
   ./target/release/releasaurus --help
   

Code Contribution Guidelines

Coding Standards

Rust Style

• Use cargo fmt for consistent formatting
• Use cargo clippy for linting
• Write comprehensive documentation comments

Adding New Language/Framework Updaters

Releasaurus supports multiple programming languages through its updater system. Adding support for a new language requires updating several files across the codebase.

Overview

Each language updater consists of:

1. ReleaseType enum variant - Configuration option in src/config/release_type.rs
2. Manifests module - Defines manifest file targets in src/updater/yourlanguage/manifests.rs
3. Updater module - Language-specific implementation in src/updater/yourlanguage/updater.rs
4. File parsers - Version file format handlers (e.g., src/updater/yourlanguage/your_file_type.rs)
5. Tests - Comprehensive test coverage for all modules
6. Documentation - User-facing documentation updates

Files to Update

1. Add ReleaseType Variant

• src/config/release_type.rs - Add your language to the ReleaseType enum

2. Create Manifests Module

• src/updater/yourlanguage/manifests.rs - Implement ManifestTargets trait
• src/updater/manager.rs - Register in release_type_manifest_targets() function

3. Create Updater Implementation

• src/updater/yourlanguage.rs - Module declaration file
• src/updater/yourlanguage/updater.rs - Implement PackageUpdater trait
• src/updater/yourlanguage/your_file_type.rs - File format parser(s)
• src/updater.rs - Add module declaration
• src/updater/manager.rs - Register in updater() function

4. Add Tests

• Tests in manifests.rs - Test manifest target generation
• Tests in updater.rs - Test updater integration
• Tests in file parser modules - Test version updates

5. Update Documentation

• book/src/supported-languages.md - Add language section
• book/src/configuration.md - Update ReleaseType options

Reference Implementations

Use existing language implementations as templates:

Simple Languages (Good starting points):

• PHP: src/updater/php/ - Single manifest file, straightforward JSON parsing
• Python: src/updater/python/ - Multiple manifest formats (TOML, cfg, py)

Complex Languages (Advanced features):

• Node: src/updater/node/ - Workspace support, multiple lock files
• Rust: src/updater/rust/ - Workspace detection, dependency updates
• Java: src/updater/java/ - Multiple build tools (Maven, Gradle), properties files

Key Traits to Implement:

• ManifestTargets in manifests.rs - Defines which files to load
• PackageUpdater in updater.rs - Coordinates version updates

Testing Guidelines

Follow the established testing patterns:

• Test outcomes, not implementation - Verify behavior, not how it’s achieved
• Minimal and concise - Only test what provides value
• Use helper functions - Reduce duplication (see test_helpers.rs)
• Descriptive names - e.g., returns_all_manifest_targets not test_1

Example test files to reference:

• src/updater/php/manifests.rs - Simple manifest tests
• src/updater/node/manifests.rs - Workspace-aware manifest tests
• src/updater/php/updater.rs - Basic updater tests

Running Tests

# Run all tests for your language
cargo test yourlanguage

# Run specific module tests
cargo test updater::yourlanguage::manifests
cargo test updater::yourlanguage::updater

# Test with real repository
releasaurus release-pr \
  --forge local \
  --repo "/path/to/test/project" \
  --debug

Best Practices

• Parse robustly - Handle various file formats and edge cases
• Preserve formatting - Maintain original file structure when possible
• Log clearly - Use info!, warn!, error! macros appropriately
• Follow patterns - Study existing implementations before starting
• Write tests first - Define expected behavior through tests

Getting Help

• Review existing implementations in src/updater/
• Check test files for usage patterns
• Ask questions in GitHub Discussions
• Reference the PackageUpdater and ManifestTargets trait documentation

Code of Conduct

This repository adheres the Rust Code of Conduct

Reporting

Report any unacceptable behavior to the project maintainers.

Community and Communication

Channels

• GitHub Issues: Bug reports and feature requests
• GitHub Discussions: General questions and community support
• Pull Requests: Code review and collaboration

Getting Help

• Documentation: Start with this book
• Search Issues: Check if your question has been asked
• Ask Questions: Create a discussion or issue
• Debug Mode: Use --debug flag or RELEASAURUS_DEBUG environment variable for troubleshooting

Thank you for contributing to Releasaurus!