Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Introduction

Releasaurus 🦕 is a comprehensive release automation tool that streamlines the software release process across multiple programming languages and Git forge platforms. Designed with simplicity and flexibility in mind, Releasaurus works out-of-the-box with little to no configuration while providing powerful customization options for advanced use cases.

What is Releasaurus?

Releasaurus automates the entire release workflow, from version detection and changelog generation to creating pull requests and publishing releases. It intelligently detects your project's language and framework, automatically handles version updates across multiple file types, and seamlessly integrates with your preferred Git hosting platform.

Key Features

🚀 Zero Configuration Start

Get started immediately without complex setup files or extensive configuration. Releasaurus intelligently detects your project structure and applies sensible defaults.

🔍 Intelligent Detection

Automatically detects your project's programming language, framework, and version files. No manual specification required for most common project structures.

🌍 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.

🤖 CI/CD Integration

Complete automation through official integrations:

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

📁 Remote Repository Operations

Works from any directory by automatically cloning repositories to temporary locations for analysis. No need to navigate to project directories or maintain local checkouts—just point at any repository URL.

📦 Multi-Language Support

Native support for:

  • Rust (Cargo.toml)
  • Node.js (package.json, package-lock.json)
  • Python (pyproject.toml, setup.py, requirements files)
  • Java (Maven pom.xml, Gradle build files)
  • PHP (composer.json)
  • Ruby (Gemfile, .gemspec files)
  • Generic projects (changelog and tagging only - no version file updates)

📝 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.

🔧 Flexible Configuration

While it works great with defaults, customize every aspect of the release process through an optional releasaurus.toml configuration file.

How It Works

Releasaurus follows a simple two-step release process:

  1. releasaurus release-pr - Analyzes your commits, determines the next version, updates version files, 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.

Why Another Release Tool?

Releasaurus was inspired by excellent tools like git-cliff, release-please, and release-plz, each of which excels in their specific domain. However, we identified key limitations that Releasaurus addresses:

  • release-please only works with GitHub, limiting teams using other platforms
  • release-plz focuses exclusively on Rust projects
  • Existing tools often require extensive configuration for non-standard projects

Releasaurus brings together the best ideas from these tools while providing:

  • Universal platform support - GitHub, GitLab, and Gitea
  • Multi-language support - Works with any programming language or framework
  • Minimal configuration - Intelligent defaults that work immediately
  • Consistent experience - Same workflow regardless of language or platform

Credit and Inspiration

We gratefully acknowledge the inspiration and foundation provided by:

Releasaurus builds upon these proven concepts while extending support to a broader ecosystem of languages, frameworks, and platforms.

Getting Started

Ready to automate your releases? Head over to the Installation guide to get started, or jump straight into the Quick Start tutorial to see Releasaurus in action.

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

This guide covers different methods to install Releasaurus on your system.

System Requirements

  • Operating System: Linux, macOS, or Windows
  • Git: Version 2.0 or higher
  • Internet Access: Required for API calls to Git forge platforms

Installation Methods

The easiest way to install Releasaurus is using Cargo, Rust's package manager:

cargo install releasaurus

This will download, compile, and install the latest stable version of Releasaurus. The binary will be available in your $HOME/.cargo/bin directory, which should be in your system's PATH.

Option 2: Download Pre-built Binaries

Coming soon...

Option 3: Build from Source

If you prefer to build from source or need the latest development features:

Prerequisites

  • Rust 1.70 or higher
  • Git

Build Steps

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

# Build and install
cargo install --path .

This will build the project in release mode and install it to your Cargo bin directory.

Option 4: Using Docker

If you prefer to use Docker, you can pull and run the official Releasaurus Docker image:

Pull the Docker Image

docker pull rgonnella/releasaurus:latest

Run Releasaurus with Docker

You can run Releasaurus directly using Docker.

# Run from your project directory
docker run --rm rgonnella/releasaurus:latest --help

Verify Installation

After installation, verify that Releasaurus is working correctly:

releasaurus --help

You should see the help output with available commands and options.

Check the installed version:

releasaurus --version

Next Steps

Now that you have Releasaurus installed, head over to the Quick Start guide to learn how to use it with your first project, or check out the Basic Configuration if you want to customize the default behavior.

Quick Start

This guide will get you up and running with Releasaurus in just a few minutes. We'll walk through releasing a simple project to demonstrate the core workflow.

Prerequisites

Before starting, ensure you have:

  1. Releasaurus installed - See Installation if you haven't already
  2. A Git repository with some commits to release
  3. Access token for your Git forge platform (GitHub, GitLab, or Gitea)
  4. Push access to your repository

Step 1: Prepare Your Access Token

Releasaurus needs an access token to create pull requests and releases on your behalf.

GitHub

  1. Go to GitHub Settings → Personal Access Tokens
  2. Generate a new token with these scopes:
    • repo (for private repositories)
    • public_repo (for public repositories)

GitLab

  1. Go to GitLab User Settings → Access Tokens
  2. Create a token with these scopes:
    • api
    • read_repository
    • write_repository

Gitea

  1. Go to your Gitea instance → User Settings → Applications
  2. Generate a new token with repository read/write permissions

Step 2: Identify Your Project Repository

You can run Releasaurus from any directory - it automatically clones your repository to a temporary location for analysis and updates. You just need the repository URL and appropriate access permissions.

Releasaurus works with any project structure and automatically detects:

  • Rust: Projects with Cargo.toml
  • Node.js: Projects with package.json
  • Python: Projects with pyproject.toml, setup.py, or setup.cfg
  • Java: Projects with pom.xml or build.gradle
  • PHP: Projects with composer.json
  • Ruby: Projects with Gemfile or .gemspec files

Step 3: Create a Release PR

Important: You can run this command from any directory. Releasaurus will automatically clone your repository to analyze it and create the release PR.

Run the release-pr command with your repository information:

# GitHub example
releasaurus release-pr \
  --github-repo "https://github.com/owner/repo" \
  --github-token "ghp_your_token_here"

# GitLab example
releasaurus release-pr \
  --gitlab-repo "https://gitlab.com/owner/repo" \
  --gitlab-token "glpat_your_token_here"

# Gitea example
releasaurus release-pr \
  --gitea-repo "https://git.example.com/owner/repo" \
  --gitea-token "your_token_here"

This command will:

  1. Analyze your commits since the last release using conventional commit patterns
  2. Determine the next version based on the changes (patch, minor, or major)
  3. Update version files in your project automatically
  4. Generate a changelog from your commit history
  5. Create a pull request with all the changes ready for review

Step 4: Review and Merge

The release PR is created in your repository regardless of where you ran the command from.

  1. Review the pull request that was created
  2. Check the changelog and version updates
  3. Make any necessary adjustments by pushing additional commits to the PR branch
  4. Merge the pull request when you're satisfied

Step 5: Publish the Release

After merging the release PR, publish the actual release:

# Use the same platform and credentials as before
releasaurus release \
  --github-repo "https://github.com/owner/repo" \
  --github-token "ghp_your_token_here"

This will:

  1. Create a Git tag for the new version
  2. Push the tag to your repository
  3. Create a release on your forge platform with the generated changelog

Environment Variables (Alternative)

Instead of passing tokens as command-line arguments, you can use environment variables:

# Set your token
export GITHUB_TOKEN="ghp_your_token_here"
# or
export GITLAB_TOKEN="glpat_your_token_here"
# or
export GITEA_TOKEN="your_token_here"

# Then run commands without --*-token flags
releasaurus release-pr --github-repo "https://github.com/owner/repo"
releasaurus release --github-repo "https://github.com/owner/repo"

Performance Considerations

For large repositories or slow network connections, you can control how much git history is downloaded:

# Clone only recent history (faster)
releasaurus release-pr \
  --github-repo "https://github.com/owner/repo" \
  --clone-depth 100

# Clone full history (slower but comprehensive)
releasaurus release-pr \
  --github-repo "https://github.com/owner/repo" \
  --clone-depth 0

The default clone depth is 250 commits, which works well for most repositories. Adjust this if:

  • Your repository is very large - Use a smaller depth like --clone-depth 50
  • Releasaurus can't find enough history - Use --clone-depth 0 for full history
  • You're in a CI/CD environment - Use a smaller depth for faster builds

What Just Happened?

Congratulations! You've just completed a full release cycle with Releasaurus:

  1. ✅ Automated version detection - No manual version bumping
  2. ✅ Automatic file updates - All version files updated consistently
  3. ✅ Generated changelog - Beautiful changelog from your commit history
  4. ✅ Safe review process - Changes reviewed via pull request
  5. ✅ Published release - Tagged and published to your forge platform

Next Steps

This quick start used all defaults, but Releasaurus is highly customizable:

Common Patterns

Workflow Integration

Many teams integrate Releasaurus into their development workflow:

# 1. Develop and commit using conventional commits (in your project directory)
git commit -m "feat: add user authentication"
git commit -m "fix: resolve login validation issue"
git commit -m "docs: update API documentation"

# 2. When ready to release (can be run from anywhere)
releasaurus release-pr --github-repo "https://github.com/owner/repo"

# 3. Review, merge, then publish (can be run from anywhere)
releasaurus release --github-repo "https://github.com/owner/repo"

Debug Mode

If something isn't working as expected, enable debug logging:

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

This provides detailed information about detection logic, API calls, and file operations.

Automation with CI/CD

While the manual workflow above works great, you can fully automate your releases using CI/CD platforms:

GitHub Actions

The official robgonnella/releasaurus-action automatically creates release PRs when you push to your main branch and publishes releases when those PRs are merged. See full action documentation for all available options.

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

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

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - name: Release
        uses: robgonnella/releasaurus-action@v1
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}

With this setup, your releases become completely hands-off:

  1. Push commits using conventional commit format to your main branch
  2. GitHub Action automatically creates a release PR with version updates and changelog
  3. Review and merge the PR when ready
  4. GitHub Action automatically publishes the release with tags and release notes

GitLab CI/CD

For GitLab projects, use the official releasaurus-component that integrates seamlessly with GitLab CI/CD pipelines. Create .gitlab-ci.yml in your repository:

include:
  - component: gitlab.com/rgon/releasaurus-component/releasaurus@~latest

See the GitLab CI/CD integration guide for complete setup instructions.

Gitea Actions

For Gitea repositories, use the official releasaurus-gitea-action that integrates seamlessly with Gitea Actions workflows. 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: Checkout
        uses: actions/checkout@v5
      - name: Run Releasaurus
        uses: https://gitea.com/rgon/releasaurus-gitea-action@v1

See the Gitea Actions integration guide for complete setup instructions.

Ready to dive deeper? Check out the Commands section for detailed information about all available options and features.

Basic Configuration

Releasaurus is designed to work out-of-the-box with zero configuration for most projects. However, you may want to customize certain aspects of the release process, such as changelog formatting or handling multiple packages within a single repository.

Do You Need Configuration?

You DON'T need configuration if:

  • You have a single package/project in your repository
  • You're happy with the default changelog format
  • You're happy with the default tag prefix "v" i.e. v1.0.0, v2.1.0
  • You're using standard project structures for supported languages

You DO need configuration if:

  • You want custom changelog templates or formatting
  • You have multiple packages in one repository (monorepo)
  • You want custom prefixed tags (like cli-v1.0.0 or api-v1.0.0)
  • You need to customize the release process for your team's workflow

Creating Your First Configuration

If you need configuration, create a file called releasaurus.toml in your project's root directory:

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

Basic Configuration Examples

Adding Tag Prefixes

The most common customization is adding a prefix to your Git tags:

# releasaurus.toml
[[package]]
path = "."
tag_prefix = "v"

This creates tags like v1.0.0, v1.1.0, v2.0.0 instead of 1.0.0, 1.1.0, 2.0.0.

Custom Changelog Header

Add a custom header to your changelogs:

# releasaurus.toml
[changelog]
header = "# MyProject Changelog\n\nAll notable changes to MyProject are documented here.\n"

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

Simple Multi-Package Setup

For a repository with multiple independently-versioned components:

# releasaurus.toml
[[package]]
path = "./frontend"
tag_prefix = "frontend-v"

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

This allows you to release the frontend and backend independently, with tags like:

  • frontend-v1.0.0, frontend-v1.1.0
  • backend-v1.0.0, backend-v2.0.0

Configuration File Structure

The configuration file has two main sections:

[changelog] Section (Optional)

Controls how changelogs are generated:

[changelog]
header = "Custom header text"    # Optional
footer = "Custom footer text"    # Optional
# body template is also available for advanced users

[[package]] Sections (Required)

Defines packages in your repository. You can have multiple [[package]] sections:

[[package]]
path = "."              # Required: path to package
tag_prefix = "v"        # Optional: tag prefix

[[package]]
path = "./other-package"
tag_prefix = "other-v"

Common Patterns

Standard Single Project

# Most common setup
[[package]]
path = "."
tag_prefix = "v"

Workspace with Shared Tag Prefix

# All packages use same prefix style
[[package]]
path = "./app"
tag_prefix = "v"

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

Clear Component Separation

# Different prefix for each component
[[package]]
path = "./web-app"
tag_prefix = "web-"

[[package]]
path = "./mobile-app"
tag_prefix = "mobile-"

[[package]]
path = "./shared-lib"
tag_prefix = "lib-"

Testing Your Configuration

After creating your configuration file:

  1. Validate syntax: Run any Releasaurus command with --debug to check for configuration errors
  2. Review output: Check that tag names and changelog format match your expectations

Example validation:

# This will load and validate your configuration
releasaurus release-pr --github-repo "https://github.com/owner/repo" --debug

If there are configuration errors, you'll see clear error messages explaining what needs to be fixed.

Configuration Loading

Releasaurus looks for releasaurus.toml in your project root. If found:

  • ✅ Your configuration is loaded and used
  • ❌ Any errors will stop execution with helpful messages

If not found:

  • ✅ Default configuration is used automatically
  • ✅ Everything works with sensible defaults

Default Values

When you don't specify values, these defaults are used:

# Implicit defaults (you don't need to write these)
[changelog]
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"

Environment-Specific Configuration

While the configuration file handles project settings, environment-specific settings use environment variables:

# Authentication tokens
export GITHUB_TOKEN="ghp_xxxxxxxxxxxx"
export GITLAB_TOKEN="glpat_xxxxxxxxxxxx"
export GITEA_TOKEN="xxxxxxxxxxxx"

These don't go in the configuration file for security reasons.

Getting Help

If you're having trouble with configuration:

  1. Use debug mode: Add --debug to see detailed configuration loading
  2. Start simple: Begin with just tag prefixes, add complexity gradually
  3. Check examples: Review the patterns above for similar use cases
  4. Validate early: Test configuration changes before committing

Next Steps

Once you have basic configuration working:

Remember: start simple and add complexity as needed. The basic patterns above handle most common requirements, and you can always enhance your configuration as your project evolves.

Commands

Releasaurus provides two main commands that work together to create a safe, reviewable release process. This two-stage approach ensures that all changes are reviewed before publication while automating the tedious aspects of version management and changelog generation.

Important: Releasaurus operates on remote repositories by automatically cloning them to temporary directories for analysis. You can run these commands from any location - you don't need to navigate to or have a local checkout of your project.

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

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

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 --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 --github-repo "https://github.com/owner/repo"

Note: These commands work by cloning your repository to a temporary directory, analyzing the project structure, making necessary changes, and pushing updates back to the remote. You don't need to be in your project directory or have a local checkout.

Global Options

All commands support these global options:

Platform Selection

Choose your Git forge platform by specifying the repository URL:

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

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

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

Authentication

Provide access tokens for API authentication:

# Via command line
--github-token "ghp_xxxxxxxxxxxxxxxxxxxx"
--gitlab-token "glpat_xxxxxxxxxxxxxxxxxxxx"
--gitea-token "xxxxxxxxxxxxxxxxxx"

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

Debug Logging

Enable detailed logging for troubleshooting:

--debug

This provides verbose output including:

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

Clone Depth Control

Control how much git history is cloned during repository operations:

--clone-depth 100    # Clone only the last 100 commits
--clone-depth 0      # Clone full history (all commits)

Default: 250 commits

The clone depth feature helps optimize performance by limiting the amount of git history downloaded during repository analysis. This is particularly useful for:

  • Large repositories with extensive commit histories
  • CI/CD environments where bandwidth and storage are limited
  • Repositories with non-linear history where full clones can be very large

When to adjust clone depth:

  • Increase the depth if Releasaurus can't find enough commit history to properly determine version changes
  • Set to 0 (full clone) if you need complete history analysis or are working with complex branching patterns
  • Decrease the depth for faster operations on repositories where recent history is sufficient

Examples:

# Quick analysis with minimal history
releasaurus release-pr \
  --github-repo "https://github.com/owner/repo" \
  --clone-depth 50

# Full history analysis
releasaurus release-pr \
  --github-repo "https://github.com/owner/repo" \
  --clone-depth 0

# Balanced approach (default)
releasaurus release-pr \
  --github-repo "https://github.com/owner/repo"
  # Uses default clone-depth of 250

Platform-Specific Examples

GitHub

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

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

GitLab

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

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

Gitea

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

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

Environment Variables

For security and convenience, use environment variables instead of command-line tokens:

VariableDescriptionExample
GITHUB_TOKENGitHub personal access tokenghp_xxxxxxxxxxxxxxxxxxxx
GITLAB_TOKENGitLab personal/project access tokenglpat_xxxxxxxxxxxxxxxxxxxx
GITEA_TOKENGitea/Forgejo access tokenxxxxxxxxxxxxxxxxxx

When environment variables are set, you can omit the --*-token flags:

# Set once
export GITHUB_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxx"

# Use in multiple commands
releasaurus release-pr --github-repo "https://github.com/org/repo1"
releasaurus release-pr --github-repo "https://github.com/org/repo2"

Help and Documentation

Get help for any command:

# General help
releasaurus --help

# Command-specific help
releasaurus release-pr --help
releasaurus release --help

# Version information
releasaurus --version

Next Steps

For integration and automation:

GitHub Actions Integration

Releasaurus provides seamless integration with GitHub Actions through the official robgonnella/releasaurus-action. This action automates your release workflow directly in your GitHub repository, eliminating the need to run Releasaurus commands manually. See action documentation] for all available options.

Basic Setup

Step 1: Create the Workflow File

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

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

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - name: Release
        uses: robgonnella/releasaurus-action@v1
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}

Step 2: Configure Repository Permissions

Ensure your repository has the correct permissions:

  1. Go to your repository Settings → Actions → General
  2. Under Workflow permissions, select Read and write permissions
  3. Check Allow GitHub Actions to create and approve pull requests

That's it! Your repository now has fully automated releases.

GitLab CI/CD Integration

Releasaurus provides seamless integration with GitLab CI/CD through the official [releasaurus-component]. This component automates your release workflow directly in your GitLab project, eliminating the need to run Releasaurus commands manually. See component [documentation][releasaurus-component] for all available options.

Basic Setup

Step 1: Create the Pipeline Configuration

Create a .gitlab-ci.yml file in your repository or add the following to your existing pipeline:

include:
  - component: gitlab.com/rgon/releasaurus-component/releasaurus@~latest
    inputs:
      token: $GITLAB_TOKEN

Step 2: Configure Project Permissions

Ensure your GitLab project has the correct permissions:

  1. Go to Settings → CI/CD → Variables
  2. Add a project variable GITLAB_TOKEN with a Personal Access Token that has:
    • api scope
    • write_repository scope

For better security, use a Project Access Token instead of a Personal Access Token:

  1. Go to Settings → Access Tokens
  2. Create a new token with:
    • Token name: releasaurus-ci
    • Role: Maintainer
    • Scopes: api, write_repository
  3. Copy the generated token
  4. Go to Settings → CI/CD → Variables
  5. Add variable GITLAB_TOKEN with the project access token as the value
  6. Mark it as Protected and Masked

Gitea Actions Integration

Releasaurus provides seamless integration with Gitea Actions through the official releasaurus-gitea-action. This action automates your release workflow directly in your Gitea repository, eliminating the need to run Releasaurus commands manually. See action documentation for all available options.

Basic Setup

Step 1: Create the Workflow File

Create a .gitea/workflows/release.yml file 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: Checkout
        uses: actions/checkout@v5
      - name: Run Releasaurus
        uses: https://gitea.com/rgon/releasaurus-gitea-action@v1

Step 2: Configure Repository Permissions

Ensure your Gitea repository has the correct permissions:

  1. Go to your repository Settings → Actions
  2. Enable Actions if not already enabled
  3. Under Secrets and Variables, add any custom tokens if needed
  4. Ensure the default GITEA_TOKEN has sufficient permissions

Step 3: Token Permissions (If Using Custom Token)

If you need to use a custom Gitea token instead of the default, ensure it has:

  • Contents: write - To create tags and releases
  • Pull requests: write - To create release pull requests
  • Issues: write - To create and manage labels

That's it! Your repository now has fully automated releases.

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

Clone Depth Problems

Issue: "Not enough commit history found"

Symptoms:

  • Releasaurus can't determine the next version
  • Error messages about missing previous releases
  • Empty or incomplete changelog generation

Cause: The default clone depth (250 commits) doesn't include enough history for analysis.

Solutions:

# Option 1: Increase clone depth
releasaurus release-pr \
  --github-repo "https://github.com/owner/repo" \
  --clone-depth 500

# Option 2: Clone full history
releasaurus release-pr \
  --github-repo "https://github.com/owner/repo" \
  --clone-depth 0

Issue: Clone operation is too slow

Symptoms:

  • Long wait times during repository cloning
  • Timeouts in CI/CD environments
  • High bandwidth usage

Cause: Repository has extensive history or large binary files.

Solutions:

# Reduce clone depth for faster operations
releasaurus release-pr \
  --github-repo "https://github.com/owner/repo" \
  --clone-depth 50

# For CI/CD environments
releasaurus release-pr \
  --github-repo "https://github.com/owner/repo" \
  --clone-depth 25

Issue: "Could not find any releases" despite having tags

Symptoms:

  • Repository has existing tags/releases
  • Releasaurus acts like it's the first release
  • Version numbers don't follow expected sequence

Causes:

  • Clone depth is too shallow to reach previous release tags.
  • Configured tag prefixes don't match existing tags

Solution:

  • Set larger clone depth to ensure last tag is included
# Ensure full history is available
releasaurus release-pr \
  --github-repo "https://github.com/owner/repo" \
  --clone-depth 0
  • Ensure configured tag prefixes in releasaurus.toml match existing tag patterns

Authentication Issues

Issue: "Authentication failed" or "401 Unauthorized"

Symptoms:

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

Solutions:

  • Check token scopes - Ensure your token has required permissions:

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
--github-repo "https://github.com/owner/repository"
--gitlab-repo "https://gitlab.com/group/project"
--gitea-repo "https://gitea.example.com/owner/repo"

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

Debug Mode

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

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

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)
    • Git version (git --version)

Supported Languages & Frameworks

Releasaurus provides native support for a wide range of programming languages and frameworks. The tool automatically detects your project's language and framework, then handles version updates across all relevant files without requiring manual configuration.

Automatic Detection

When you run Releasaurus, it automatically scans your project directory to identify:

  1. Primary language/framework based on manifest files
  2. Version files that need updating
  3. Project structure and dependencies
  4. Release patterns appropriate for your ecosystem

This detection happens transparently—you don't need to specify your project type or configure file patterns.

Detection Priority

When multiple language indicators are present, Releasaurus uses this priority order:

  1. Rust - Cargo.toml presence
  2. Python - pyproject.toml, setup.py, or setup.cfg
  3. Node.js - package.json presence
  4. PHP - composer.json presence
  5. Java - pom.xml or build.gradle* files
  6. Ruby - Gemfile or *.gemspec files
  7. Generic - Custom patterns or unrecognized projects

Supported Languages

Rust

Detection Files: Cargo.toml Updated Files: Cargo.toml, Cargo.lock (if present)

Rust projects using Cargo for dependency management and packaging. Supports both library and binary crates, workspace configurations, and dependency version updates.

Example Project Structure:

my-rust-project/
├── Cargo.toml          # ← Version updated here
├── Cargo.lock          # ← Automatically updated
├── src/
│   └── lib.rs
└── README.md

Node.js

Detection Files: package.json Updated Files: package.json, package-lock.json, yarn.lock, pnpm-lock.yaml

JavaScript and TypeScript projects using npm, Yarn, or pnpm package managers. Supports monorepos, workspaces, and dependency updates.

Example Project Structure:

my-node-project/
├── package.json        # ← Version updated here
├── package-lock.json   # ← Automatically updated
├── src/
│   └── index.js
└── README.md

Python

Detection Files: pyproject.toml, setup.py, setup.cfg Updated Files: pyproject.toml, setup.py, setup.cfg, __init__.py, requirements*.txt

Python projects using modern packaging standards (PEP 518/517) or legacy setuptools. Supports Poetry, setuptools, and custom version patterns.

Example Project Structure:

my-python-project/
├── pyproject.toml      # ← Primary version location
├── requirements.txt    # ← Version references updated
├── src/
│   └── my_package/
│       └── __init__.py # ← Version string updated
└── README.md

Java

Detection Files: pom.xml, build.gradle, build.gradle.kts Updated Files: Maven POMs, Gradle build files, version properties

Java projects using Maven or Gradle build systems. Supports multi-module projects, parent POMs, and version property management.

Example Maven Project:

my-java-project/
├── pom.xml             # ← Version updated here
├── src/
│   └── main/java/
└── README.md

Example Gradle Project:

my-gradle-project/
├── build.gradle        # ← Version updated here
├── gradle.properties   # ← Version properties updated
├── src/
│   └── main/java/
└── README.md

PHP

Detection Files: composer.json Updated Files: composer.json, composer.lock (regenerated)

PHP projects using Composer for dependency management. Supports packages, applications, and dependency constraint updates.

Example Project Structure:

my-php-project/
├── composer.json       # ← Version updated here
├── composer.lock       # ← Automatically updated
├── src/
│   └── MyClass.php
└── README.md

Ruby

Detection Files: Gemfile, *.gemspec Updated Files: Gemspec files, version files, Gemfile dependencies

Ruby projects using Bundler and RubyGems. Supports gems, applications, and version constant management.

Example Gem Project:

my-ruby-gem/
├── my_gem.gemspec      # ← Version updated here
├── Gemfile
├── lib/
│   └── my_gem/
│       └── version.rb  # ← Version constant updated
└── README.md

Generic Projects

Detection: Fallback when no specific language is detected

Right now anything that falls back to "Generic" will only receive changelog updates and tagging. Any specific version manifests will be left untouched. In the future we will support the configuration of generic manifest files that can be updated via regex-able version properties.

Framework-Specific Features

Version File Detection

Each language ecosystem has different conventions for where version information is stored:

  • Rust: Single source of truth in Cargo.toml
  • Node.js: Primary in package.json, locks updated automatically
  • Python: Multiple possible locations (pyproject.toml, setup.py, init.py)
  • Java: Maven coordinates or Gradle version properties
  • PHP: Composer metadata with semantic versioning
  • Ruby: Gemspec version specifications

Dependency Updates

Some frameworks support updating dependency versions during releases:

  • Node.js: Updates lock files and can bump dependencies
  • Rust: Updates Cargo.lock automatically
  • PHP: Regenerates composer.lock with new constraints
  • Python: Can update version pins in requirements files

Build System Integration

Releasaurus integrates with various build systems:

  • Cargo (Rust): Workspace and crate management
  • npm/yarn/pnpm (Node.js): Workspace and package management
  • Poetry/setuptools (Python): Build backend integration
  • Maven/Gradle (Java): Multi-module project support
  • Bundler (Ruby): Gem dependency management

Multi-Language Projects

For projects that use multiple languages, Releasaurus can handle them in several ways:

  1. Primary Language Detection: Uses the highest-priority language found
  2. Multi-Package Configuration: Define separate packages for each language
  3. Generic Fallback: Use generic patterns for unsupported combinations

Example multi-language project configuration:

# releasaurus.toml
[[package]]
path = "./backend"      # Rust API
tag_prefix = "api-v"

[[package]]
path = "./frontend"     # Node.js frontend
tag_prefix = "ui-v"

[[package]]
path = "./scripts"      # Python utilities
tag_prefix = "scripts-v"

Adding New Languages

Releasaurus is designed to be extensible. Each language implementation includes:

  • Detector: Identifies if the language is present
  • Updater: Handles version file modifications
  • Framework Integration: Language-specific patterns and conventions

See the Contributing guide for information about adding support for new languages and frameworks.

Next Steps

  • Refer to the language-specific sections above for detailed information about supported features
  • Explore Configuration for customization options

Git Forge Platforms

Releasaurus provides unified support for multiple Git forge platforms, allowing you to use the same workflow regardless of where your repositories are hosted. Whether you're using GitHub, GitLab, Gitea, or self-hosted instances, Releasaurus adapts seamlessly to your platform's API and conventions.

Supported Platforms

GitHub

Authentication:

  • Personal Access Tokens (classic)
  • Fine-grained Personal Access Tokens
  • Environment variable: GITHUB_TOKEN

Example Usage:

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

GitLab

Authentication:

  • Personal Access Tokens
  • Environment variable: GITLAB_TOKEN

Example Usage:

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

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

CI/CD Integration:

For automated releases with GitLab CI/CD pipelines, see the dedicated GitLab CI/CD integration guide.

Gitea

Authentication:

  • Access Tokens
  • Environment variable: GITEA_TOKEN

Example Usage:

releasaurus release-pr --gitea-repo "https://git.company.com/team/project"
releasaurus release --gitea-repo "https://git.company.com/team/project"

Actions Integration:

For automated releases with Gitea Actions workflows, see the dedicated Gitea Actions integration guide.

Authentication Methods

All platforms use token-based authentication for security and API access:

Command-Line Tokens

Pass tokens directly as command-line arguments:

# GitHub
releasaurus release-pr \
  --github-repo "https://github.com/owner/repo" \
  --github-token "ghp_xxxxxxxxxxxxxxxxxxxx"

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

# Gitea
releasaurus release-pr \
  --gitea-repo "https://git.example.com/owner/repo" \
  --gitea-token "xxxxxxxxxxxxxxxxxx"

Environment Variables

Store tokens in environment variables for security and convenience:

# Set tokens
export GITHUB_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxx"
export GITLAB_TOKEN="glpat_xxxxxxxxxxxxxxxxxxxx"
export GITEA_TOKEN="xxxxxxxxxxxxxxxxxx"

# Use without --*-token flags
releasaurus release-pr --github-repo "https://github.com/owner/repo"
releasaurus release-pr --gitlab-repo "https://gitlab.com/owner/repo"
releasaurus release-pr --gitea-repo "https://git.example.com/owner/repo"

URL Formats

Always use complete HTTP / HTTPS URLs for repository specification:

# Correct formats
--github-repo "https://github.com/owner/repo"
--gitlab-repo "https://gitlab.com/group/subgroup/project"
--gitea-repo "https://git.example.com/organization/repository"

# Incorrect formats (won't work)
--github-repo "github.com/owner/repo"           # Missing protocol
--github-repo "git@github.com:owner/repo.git"  # SSH format not supported

Next Steps

  • Refer to the platform-specific sections above for detailed information about supported features
  • Check Troubleshooting for common issues

The unified forge platform support in Releasaurus means you can focus on your release process rather than platform-specific differences, enabling consistent workflows across your entire organization's repositories.

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.

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

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

Required Scopes:

  • repo (for private repositories)
  • public_repo (for public repositories)
  • write:packages (if publishing packages)

Example:

export GITHUB_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxx"

Usage:

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

# Without environment variable (less secure)
releasaurus release-pr \
  --github-repo "https://github.com/owner/repo" \
  --github-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 --gitlab-repo "https://gitlab.com/group/project"

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

GITEA_TOKEN

Purpose: Authentication token for Gitea/Forge API access

Required Permissions:

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

Example:

export GITEA_TOKEN="xxxxxxxxxxxxxxxxxx"

Usage:

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

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

Command-Line Options vs Environment Variables

While this page focuses on environment variables, note that some configuration options are provided via command-line flags rather than environment variables.

Performance Options

Clone Depth: Controls how much git history is downloaded during repository operations.

# Command-line option (not an environment variable)
releasaurus release-pr \
  --github-repo "https://github.com/owner/repo" \
  --clone-depth 100

For detailed information about clone depth and other command-line options, see the Commands section.

Next Steps

Why Releasaurus?

The software development landscape is rich with release automation tools, each solving specific problems within their domains. So why create another one? Releasaurus was born from real-world frustrations with existing tools and a vision for what release automation could be: universal, intelligent, and effortless.

The Release Automation Challenge

Modern software development involves complex release processes that traditionally require significant manual effort:

  • Version Management: Updating version numbers across multiple files and formats
  • Changelog Generation: Creating meaningful release notes from commit history
  • Platform Integration: Working with different Git forge APIs (GitHub, GitLab, Gitea)
  • Multi-Language Support: Handling different packaging systems and conventions
  • Review Workflows: Ensuring releases go through proper review processes
  • Consistency: Maintaining uniform practices across projects and teams

While several excellent tools address parts of this challenge, none provided a complete, universal solution that works seamlessly across all environments.

The Existing Landscape

Before Releasaurus, developers had to choose between specialized tools, each with significant limitations:

release-please: GitHub-Only Excellence

release-please pioneered the release-PR workflow and remains excellent for GitHub-centric organizations. However:

  • Platform Lock-in: Only works with GitHub, excluding GitLab and Gitea users

release-plz: Rust Ecosystem Specialist

release-plz provides outstanding Rust support with deep Cargo integration. But:

  • Single Language: Only supports Rust projects
  • Ecosystem Specific: Designed exclusively for the Rust/Cargo ecosystem

git-cliff: Powerful but Manual

git-cliff excels at changelog generation with extensive customization and inspired our approach to commit parsing and changelog formatting. However, as a standalone tool it has some limitations for complete release automation:

  • Changelog Only: Doesn't handle version updates or release automation
  • Manual Process: Requires additional tooling for complete release workflows
  • No Platform Integration: Doesn't create releases or pull requests

Releasaurus

Releasaurus was designed to combine the best aspects of existing tools while eliminating their limitations. Our core principles:

🌍 Universal Platform Support

Problem: Teams using GitLab, Gitea, or mixed environments were left behind by GitHub-only tools.

Solution: First-class support for GitHub, GitLab, and Gitea with identical workflows across all platforms. Whether your repositories are hosted on github.com, self-hosted GitLab, or Gitea instances, Releasaurus works seamlessly.

# Same workflow, different platforms
releasaurus release-pr --github-repo "https://github.com/team/project"
releasaurus release-pr --gitlab-repo "https://gitlab.company.com/team/project"
releasaurus release-pr --gitea-repo "https://git.company.com/team/project"

🔍 Intelligent Zero-Configuration

Problem: Complex setup requirements create barriers to adoption and maintenance overhead.

Solution: Intelligent detection that works immediately without configuration files, setup scripts, or complex onboarding. Releasaurus analyzes your project structure and applies appropriate conventions automatically.

  • Language Detection: Automatically identifies Rust, Node.js, Python, Java, PHP, Ruby, or generic projects
  • Version File Discovery: Finds and updates all relevant version files for supported languages (generic projects receive changelog and tagging only)
  • Framework Integration: Adapts to your project's specific packaging and build systems
  • Sensible Defaults: Provides beautiful changelogs and workflows out-of-the-box

🚀 Multi-Language Native Support

Problem: Polyglot projects and organizations needed different tools for different languages.

Solution: Native support for major programming languages with deep understanding of each ecosystem's manifest files

LanguagePackage FilesLock Files
RustCargo.tomlCargo.lock
Node.jspackage.jsonpackage-lock.json, yarn.lock
Pythonpyproject.toml, setup.pyVarious
Javapom.xml, build.gradleMaven/Gradle locks
PHPcomposer.jsoncomposer.lock
Ruby*.gemspec, GemfileGemfile.lock

The Philosophy

Releasaurus embodies several key philosophical principles:

Intelligent Automation Over Configuration

Rather than requiring users to specify every detail, Releasaurus makes intelligent decisions based on project analysis. Configuration is available for customization, but not required for effectiveness.

Universal Over Specialized

While specialized tools excel in narrow domains, Releasaurus prioritizes universal applicability. This enables consistent workflows across diverse projects and teams.

Simplicity Over Features

Every feature must justify its existence by solving a real problem without adding unnecessary complexity. Power users have customization options, but they don't interfere with simple use cases.

Credit to existing projects

Releasaurus wouldn't exist without the pioneering work of existing tools:

We're grateful for these tools and the problems they solved. Releasaurus builds upon their innovations while implementing our own solutions to address the gaps that remained.

When to Choose Releasaurus

Choose Releasaurus if you:

  • Work with multiple programming languages or frameworks
  • Use GitLab, Gitea, or mixed Git hosting platforms
  • Want release automation that works immediately without complex setup
  • Need consistent workflows across diverse projects
  • Value safety and review processes in your release workflow
  • Want to minimize time spent on release mechanics

Consider alternatives if you:

  • Are deeply committed to GitHub-only workflows and love release-please
  • Need features specific to a single language ecosystem
  • Require extensive customization beyond what templates provide
  • Have unique release requirements not covered by conventional patterns

The Future

Releasaurus continues to evolve based on real-world usage and community feedback. Our roadmap includes:

  • Additional Language Support: Expanding to more programming languages and frameworks
  • Enhanced CI/CD Integration: Deeper integration with popular CI/CD platforms
  • Advanced Monorepo Features: More sophisticated dependency and release coordination
  • Custom Workflow Support: Extensibility for unique release requirements

But our core mission remains constant: making software releases effortless, safe, and universal.

Getting Started

Ready to experience effortless releases? The Quick Start guide will have you releasing software in minutes, not hours. Or dive into the Installation instructions to get Releasaurus set up in your environment.

Remember: great software deserves great releases. Let Releasaurus handle the mechanics so you can focus on building amazing things. 🦕

Comparison with Other Tools

The release automation ecosystem includes several excellent tools, each with unique strengths and target audiences. This comparison helps you understand where Releasaurus fits in the landscape and when you might choose it over alternatives.

Quick Comparison Table

ToolPlatformsLanguagesConfig RequiredProcessBest For
ReleasaurusGitHub, GitLab, GiteaRust, Node.js, Python, Java, PHP, Ruby, Generic (limited)OptionalRelease PR → PublishUniversal, multi-platform, zero-config
release-pleaseGitHub onlyMany (via plugins)Required for mostRelease PR → PublishGitHub-only orgs
release-plzGitHub, crates.ioRust onlyMinimalRelease PR → PublishRust projects, Cargo ecosystems
git-cliffAny Git hostLanguage agnosticRequiredManual changelogChangelog generation only
semantic-releaseGitHub, GitLab, npmJavaScript-focusedRequiredDirect publishNode.js projects, automated releases

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

Project Structure

releasaurus/
├── src/
│   ├── analyzer/         # Commit analysis and changelog generation
│   ├── command/          # CLI command implementations
│   ├── config.rs         # Configuration file handling
│   ├── forge/            # Git forge platform integrations
│   │   ├── github.rs     # GitHub API client
│   │   ├── gitlab.rs     # GitLab API client
│   │   └── gitea.rs      # Gitea API client
│   ├── repo.rs           # Git repository operations
│   ├── updater/          # Version file update logic
│   │   ├── rust.rs       # Rust/Cargo support
│   │   ├── node.rs       # Node.js support
│   │   ├── python.rs     # Python support
│   │   └── ...           # Other language implementations
│   └── main.rs           # Application entry point
├── tests/                # Integration tests
├── book/                 # Documentation (mdBook)
├── Cargo.toml            # Rust project configuration
└── README.md

Code Contribution Guidelines

Coding Standards

Rust Style

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

Error Handling

#![allow(unused)]
fn main() {
// Use the project's Result type
use crate::result::Result;

// Provide context for errors
fn update_version_file(path: &Path) -> Result<()> {
    fs::write(path, content)
        .with_context(|| format!("Failed to write version file: {}", path.display()))?;
    Ok(())
}
}

Adding Language Support

To add support for a new programming language:

  1. Create Language Module

    #![allow(unused)]
fn main() {
// src/updater/newlang.rs
use crate::updater::traits::PackageUpdater;

pub struct NewLangUpdater;

impl PackageUpdater for NewLangUpdater {
    fn update(&self, root_path: &Path, packages: Vec<Package>) -> Result<()> {
        // Implementation
    }
}
}

  2. Add Detection Logic

    #![allow(unused)]
fn main() {
// src/updater/detection/newlang.rs
use crate::updater::detection::traits::FrameworkDetector;

pub struct NewLangDetector;

impl FrameworkDetector for NewLangDetector {
  fn detect(&self, path: &Path) -> Result<FrameworkDetection> {
      let pattern = DetectionPattern {
          manifest_files: vec!["<some_manifest_file>"],
          support_files: vec!["<some_support_file>", "<another_support_file>"],
          content_patterns: vec![
              "[package]",
              "[workspace]",
              "[dependencies]",
          ],
          base_confidence: 0.8,
      };

      DetectionHelper::analyze_with_pattern(
          path,
          pattern.clone(),
          |support_evidence| FrameworkDetection {
              framework: Framework::NewLang,
              confidence: DetectionHelper::calculate_confidence(
                  &pattern,
                  &support_evidence,
              ),
              evidence: support_evidence,
          },
      )
  }
}
}

  3. Register in Framework System

    #![allow(unused)]
fn main() {
// src/updater/framework.rs
pub enum Framework {
    // ... existing frameworks
    NewLang,
}

impl Framework {
    pub fn detection_manager(root_path: PathBuf) -> DetectionManager {
        let detectors: Vec<Box<dyn FrameworkDetector>> = vec![
            // ... existing detectors
            Box::new(NewLangDetector::new()),
        ];
        DetectionManager::new(root_path, detectors)
    }
}
}

  4. Add Tests

    #![allow(unused)]
fn main() {
#[cfg(test)]
mod tests {
    use super::*;
    use tempfile::TempDir;

    #[test]
    fn test_newlang_detection() {
        let temp_dir = TempDir::new().unwrap();
        let path = temp_dir.path();

        // Create test files
        std::fs::write(path.join("package.newlang"), "version = \"1.0.0\"").unwrap();

        let detector = NewLangDetector::new();
        let result = detector.detect(path);

        assert!(matches!(result, DetectionResult::Detected { .. }));
    }
}
}

Adding Forge Platform Support

To add support for a new Git forge platform:

  1. Create Platform Module

    #![allow(unused)]
fn main() {
// src/forge/newforge.rs
use crate::forge::traits::ForgeClient;
use crate::forge::types::{PullRequest, Release};

pub struct NewForgeClient {
    config: RemoteConfig,
    client: reqwest::Client,
}

#[async_trait]
impl ForgeClient for NewForgeClient {
    async fn create_pull_request(&self, pr: &PullRequest) -> Result<String> {
        // Implementation
    }

    async fn create_release(&self, release: &Release) -> Result<String> {
        // Implementation
    }
}
}

  2. Add CLI Integration

    #![allow(unused)]
fn main() {
// src/cli.rs
pub struct Args {
    // ... existing fields

    #[arg(long, default_value = "", global = true)]
    /// NewForge repository URL
    pub newforge_repo: String,

    #[arg(long, default_value = "", global = true)]
    /// NewForge authentication token
    pub newforge_token: String,
}
}

  3. Update Command Logic

    #![allow(unused)]
fn main() {
// src/command/common.rs
pub fn determine_forge_client(args: &Args) -> Result<Box<dyn ForgeClient>> {
    if !args.newforge_repo.is_empty() {
        return Ok(Box::new(NewForgeClient::new(/* config */)?));
    }
    // ... existing logic
}
}

Testing

Test Categories

Unit Tests

# Run all unit tests
cargo test

# Run tests for specific module
cargo test updater::rust

# Run with output
cargo test -- --nocapture

E2E Tests

These tests can be found in ./src/command/tests

# Run e2e tests (requires test tokens)
cargo test --features _internal_e2e_tests

# Run specific integration test
cargo test --features _internal_e2e_tests github_e2e_test

# These tests create actual repositories and releases
# Use with caution and dedicated test accounts

Commit Messages

Follow Conventional Commits:

# Features
feat: add support for Go projects
feat(forge): add Codeberg integration

# Bug fixes
fix: resolve GitHub API rate limiting
fix(updater): handle malformed package.json files

# Documentation
docs: add troubleshooting guide for Windows
docs(config): clarify multi-package setup

# Tests
test: add integration tests for GitLab
test(updater): improve Python detection tests

# Chores
chore: update dependencies
chore(ci): add automated security scanning

Pull Request Description Template

## Description

Brief description of changes.

## Type of Change

- [ ] Bug fix (non-breaking change fixing an issue)
- [ ] New feature (non-breaking change adding functionality)
- [ ] Breaking change (fix or feature causing existing functionality to change)
- [ ] Documentation update

## Testing

- [ ] Unit tests pass
- [ ] Integration tests pass (if applicable)
- [ ] Manual testing completed
- [ ] Documentation tested (if applicable)

## Related Issues

Fixes #123
Relates to #456

## Additional Notes

Any additional context or screenshots.

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 for troubleshooting

Thank you for contributing to Releasaurus!