Releasaurus

https://releasaurus.rgon.io
Admin
Releasaurus is a comprehensive release automation tool that generates changelogs, manages version...
Tokens:51,073
Snippets:741
Trust Score:2.2
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install Releasaurus with cargo-binstall

Source: https://releasaurus.rgon.io/installation.html

Use this command for the quickest setup, as it downloads a pre-compiled binary.

```bash
cargo binstall releasaurus
```

--------------------------------

### Prerelease Versioned Example 3 (Switching Suffix)

Source: https://releasaurus.rgon.io/print.html

Illustrates switching the prerelease suffix from 'alpha' to 'beta'. This resets the version to 'v1.1.0-beta.1' and starts a new counter.

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

```

--------------------------------

### Release Workflow Example

Source: https://releasaurus.rgon.io/commands.html

An example workflow demonstrating how to generate release data, transform it using an external script, and then recompile the notes with the transformations applied.

```bash
# 1. Generate release data
releasaurus get next-release --out-file releases.json \
  --forge github --repo "https://github.com/owner/repo"

# 2. Transform data (e.g., replace author names with Slack IDs)
python transform_authors.py releases.json

# 3. Regenerate notes with transformations
releasaurus get recompiled-notes --file releases.json \
  --forge github --repo "https://github.com/owner/repo"
```

--------------------------------

### Install Dependencies with Mise

Source: https://releasaurus.rgon.io/contributing.html

Install Rust and other development dependencies using Mise. Ensure Mise is installed and activated.

```bash
mise trust
mise install
```

--------------------------------

### Monorepo: Frontend + Backend + Shared Library Example

Source: https://releasaurus.rgon.io/configuration-monorepo.html

Example configuration for a monorepo with frontend, backend, and a shared library, using separate pull requests for each package.

```toml
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"
```

--------------------------------

### Static Strategy: Starting a Prerelease

Source: https://releasaurus.rgon.io/configuration-prerelease.html

When starting a prerelease with the 'static' strategy, the fixed suffix is applied without a counter.

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

```

--------------------------------

### Prerelease Graduation Example

Source: https://releasaurus.rgon.io/print.html

Shows how to graduate from a prerelease to a stable version by removing the prerelease configuration. The result is 'v1.0.0'.

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

```

--------------------------------

### Versioned Strategy: Starting a Prerelease

Source: https://releasaurus.rgon.io/configuration-prerelease.html

When starting a prerelease with the 'versioned' strategy, a new incremental counter is applied.

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

```

--------------------------------

### Prerelease Static Example

Source: https://releasaurus.rgon.io/print.html

Demonstrates the 'static' prerelease strategy, where a 'fix' commit updates the version to 'v1.0.1-SNAPSHOT' using a fixed 'SNAPSHOT' suffix without an incremental counter.

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

```

--------------------------------

### Prerelease Versioned Example 1

Source: https://releasaurus.rgon.io/print.html

Demonstrates how a 'feat' commit updates a version from 'v1.0.0' to 'v1.1.0-alpha.1' with 'alpha' prerelease suffix and versioned strategy.

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

```

--------------------------------

### Prerelease Configuration (Multiple Packages)

Source: https://releasaurus.rgon.io/print.html

Configure prereleases for multiple packages, allowing overrides for specific packages. This example sets a global 'beta' prerelease and overrides one package to 'alpha'.

```toml
[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

```

--------------------------------

### Install Releasaurus with cargo install

Source: https://releasaurus.rgon.io/installation.html

Compile Releasaurus from source using Rust's package registry. This method takes longer but ensures system compatibility.

```bash
cargo install releasaurus
```

--------------------------------

### Verify Releasaurus Installation

Source: https://releasaurus.rgon.io/installation.html

Confirm that Releasaurus has been installed correctly by checking its version.

```bash
releasaurus --version
```

--------------------------------

### Basic Node.js Project Configuration

Source: https://releasaurus.rgon.io/configuration.html

Configure Releasaurus for a single Node.js package. This is the most common setup.

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

```

--------------------------------

### Prerelease Versioned Example 2

Source: https://releasaurus.rgon.io/print.html

Shows how a subsequent 'fix' commit increments the prerelease counter from 'v1.1.0-alpha.1' to 'v1.1.0-alpha.2' with the same configuration.

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

```

--------------------------------

### Inspect projected releases with `get next-release`

Source: https://releasaurus.rgon.io/troubleshooting.html

Use the `get next-release` command to preview upcoming releases. You can inspect all projected releases, a specific package, or save the output to a file for detailed analysis.

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

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

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

```

--------------------------------

### Monorepo with Mixed Prerelease States

Source: https://releasaurus.rgon.io/configuration-prerelease.html

Example configuration for a monorepo where different packages might have distinct prerelease configurations or states.

```toml
__
# Most packages stable, some experimental
separate_pull_requests = true

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

```

--------------------------------

### Custom Changelog Body Template Example

Source: https://releasaurus.rgon.io/print.html

An example of a custom changelog body template using Tera syntax to display the release version, date, and grouped commits with their messages and short IDs.

```toml
__
[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 %} """

```

--------------------------------

### Get Releasaurus Help Information

Source: https://releasaurus.rgon.io/print.html

Access help documentation for Releasaurus commands. Use `--help` for general command information or to get help for specific subcommands.

```bash
# General help
releasaurus --help

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

# Version information
releasaurus --version
```

--------------------------------

### Start Next Development Cycle with Releasaurus

Source: https://releasaurus.rgon.io/commands.html

Use `start-next` to prepare for the next development cycle by bumping patch versions and creating chore commits. This command does not create pull requests or tags. Supports filtering to specific packages and dry-run mode.

```bash
releasaurus start-next \
  --forge github \
  --repo "https://github.com/owner/repo"
```

```bash
releasaurus start-next \
  --forge github \
  --repo "https://github.com/owner/repo" \
  --packages pkg-a,pkg-b
```

--------------------------------

### Custom Changelog Body Template Example

Source: https://releasaurus.rgon.io/configuration-changelog.html

An example of a custom Tera template for the changelog body, focusing on a simpler structure with version, release date, and grouped commit messages.

```toml
__
[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 %} """


```

--------------------------------

### Get General Help for Releasaurus

Source: https://releasaurus.rgon.io/commands.html

Use this command to display general help information for the Releasaurus CLI. This is useful for understanding the overall structure and available top-level commands.

```bash
releasaurus --help
```

--------------------------------

### Monorepo: Microservices Repository Example

Source: https://releasaurus.rgon.io/configuration-monorepo.html

Configuration for a microservices repository where each service is managed as an independent package, utilizing separate pull requests.

```toml
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"
```

--------------------------------

### Get Command-Specific Help

Source: https://releasaurus.rgon.io/commands.html

To get detailed help for a specific Releasaurus command, append '--help' after the command name. This provides information on subcommands, options, and usage for that particular command.

```bash
releasaurus <cmd> --help
```

--------------------------------

### Use GitLab Token for Release PR

Source: https://releasaurus.rgon.io/environment-variables.html

Example of using the `releasaurus release-pr` command with GitLab. The command automatically uses the `GITLAB_TOKEN` environment variable if set. Examples are shown for both GitLab.com and self-hosted instances.

```bash
# 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"
```

--------------------------------

### Automated Release Workflow

Source: https://releasaurus.rgon.io/print.html

Outlines the steps for automating the release process: creating a release preparation PR, merging it via the web interface, publishing the release, and optionally starting the next development cycle. These commands operate via the forge API without needing a local clone.

```bash
# 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"
```

--------------------------------

### Start Next Release Cycle

Source: https://releasaurus.rgon.io/commands.html

Use this command after merging a release PR to bump versions for the next development cycle. It commits directly to the base branch, so ensure you have the necessary permissions.

```bash
releasaurus start-next \
  --forge github \
  --repo "https://github.com/owner/repo" \
  --base-branch develop
```

--------------------------------

### Using Local Path for Git Operations (GitLab)

Source: https://releasaurus.rgon.io/print.html

This example shows how to use the `--local-path` option with GitLab to leverage a local repository checkout for Git operations while creating PRs on the remote platform.

```bash
# GitLab
releasaurus release-pr \
  --forge gitlab \
  --repo "https://gitlab.com/owner/repo" \
  --token "$GITLAB_TOKEN" \
  --local-path /path/to/checkout
```

--------------------------------

### Build Latest Development Version of Releasaurus

Source: https://releasaurus.rgon.io/installation.html

Clone the repository and install the latest development version from source. Requires Rust 1.80+ and Git.

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

--------------------------------

### Disable Auto Start Next for Package

Source: https://releasaurus.rgon.io/configuration-reference.html

Override the global `auto_start_next` setting for a specific package. Set to `false` to prevent automatic advancement to the next release stage.

```toml
__
[[package]]
path = "."
release_type = "node"
auto_start_next = false

```

--------------------------------

### Monorepo Package Targeting

Source: https://releasaurus.rgon.io/commands.html

In monorepo setups, target specific packages for release preparation and publishing using the `--package` flag. This allows for granular control over which part of the monorepo is included in a release.

```bash
releasaurus release-pr \
  --package frontend \
  --forge github \
  --repo "https://github.com/owner/repo"
```

```bash
releasaurus release \
  --package frontend \
  --forge github \
  --repo "https://github.com/owner/repo"
```

--------------------------------

### Start Next Release Cycle for All Packages

Source: https://releasaurus.rgon.io/print.html

Prepare for the next development cycle by automatically bumping patch versions for all packages. This command creates 'chore' commits directly on the base branch and does not create pull requests or tags.

```bash
releasaurus start-next \
  --forge github \
  --repo "https://github.com/owner/repo"
```

--------------------------------

### Test locally without authentication

Source: https://releasaurus.rgon.io/troubleshooting.html

Use this command to test version calculation, commit analysis, configuration, release notes preview, tag matching, and monorepo setup locally without authentication.

```bash
releasaurus get next-release --forge local --repo "."
```

--------------------------------

### Build and Run Project with Just

Source: https://releasaurus.rgon.io/contributing.html

Use Just commands for common development tasks like building the project or running the CLI. Run 'just help' to see all available recipes.

```bash
just build
just build --release
just run
just run --help
just help
```

--------------------------------

### Set Up Authentication Tokens

Source: https://releasaurus.rgon.io/quick-start.html

Before creating actual releases, set the appropriate environment variables for your forge. This is required for GitHub, GitLab, and Gitea.

```bash
# GitHub
export GITHUB_TOKEN="ghp_your_token_here"

# GitLab
export GITLAB_TOKEN="glpat_your_token_here"

# Gitea
export GITEA_TOKEN="your_token_here"

```

--------------------------------

### Build and Run Project with Just

Source: https://releasaurus.rgon.io/print.html

Utilize Just commands for common development tasks such as building the project, running the CLI, and viewing available commands.

```bash
just build # builds the project
just build --release # builds a release version
just run # builds and run the releasaurus cli in one command
# For example
just run --help
# Is equivalent to `cargo run -p releasaurus -- --help`
just help # show all available just recipes and their descriptions
```

--------------------------------

### Start Next Development Cycle

Source: https://releasaurus.rgon.io/commands.html

Initiates the next development cycle by bumping package versions and committing directly to the base branch. This command is typically used after merging a release PR and publishing a release to keep manifest versions ahead of released versions.

```APIDOC
## releasaurus start-next

### Description
Starts the next development cycle by bumping package versions and committing directly to the base branch.

### Method
CLI Command

### Parameters
#### Path Parameters
None

#### Query Parameters
- `--forge` (string) - Required - The forge to use (e.g., github).
- `--repo` (string) - Required - The repository URL.
- `--base-branch` (string) - Optional - The base branch to commit to. Defaults to the repository's default branch.

### Request Example
```bash
releasaurus start-next \
  --forge github \
  --repo "https://github.com/owner/repo" \
  --base-branch develop
```

### Response
Commits directly to the base branch without creating a pull request.
```

--------------------------------

### Use GitHub Token for Release PR

Source: https://releasaurus.rgon.io/environment-variables.html

Example of using the `releasaurus release-pr` command with the GitHub token set via an environment variable. Alternatively, the token can be provided directly using the `--token` flag, though this is less secure.

```bash
# 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"
```

--------------------------------

### Use Gitea Token for Release PR

Source: https://releasaurus.rgon.io/environment-variables.html

Example of using the `releasaurus release-pr` command with Gitea or Forgejo. The command selects the appropriate token based on the `--forge` flag, using the `GITEA_TOKEN` environment variable if set.

```bash
# 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"
```

--------------------------------

### Static Strategy: Graduating to Stable

Source: https://releasaurus.rgon.io/configuration-prerelease.html

To graduate to a stable release from a static prerelease, remove the prerelease configuration.

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

```

--------------------------------

### Specify Additional Manifest Files (Simple)

Source: https://releasaurus.rgon.io/print.html

Use the simple string path format for common version files like VERSION or README.md. Paths are relative to the package path.

```toml
__
[[package]]
path = "."
release_type = "rust"
additional_manifest_files = ["VERSION", "README.md", "docs/installation.md"]

```

--------------------------------

### Basic Release Workflow Commands

Source: https://releasaurus.rgon.io/commands.html

These commands initiate the release process. Use `release-pr` to prepare a pull request for a new release and `release` to publish it. The `start-next` command is for initiating the next development cycle.

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

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

```bash
releasaurus start-next \
  --forge github \
  --repo "https://github.com/owner/repo"
```

--------------------------------

### Clone Releasaurus Repository

Source: https://releasaurus.rgon.io/contributing.html

Clone the Releasaurus repository to your local machine. Ensure you have Git installed.

```bash
git clone https://github.com/your-username/releasaurus.git
cd releasaurus
```

--------------------------------

### Add Additional Manifest Files (Simple Format)

Source: https://releasaurus.rgon.io/configuration-reference.html

Specify additional files, like `VERSION` or `README.md`, to update with version strings using default regex patterns. Paths are relative to the package path.

```toml
__
[[package]]
path = "."
release_type = "rust"
additional_manifest_files = ["VERSION", "README.md", "docs/installation.md"]


```

--------------------------------

### Use Gitea Token with Releasaurus

Source: https://releasaurus.rgon.io/print.html

Examples of using Releasaurus with the GITEA_TOKEN environment variable for self-hosted Gitea and Forgejo instances.

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

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

--------------------------------

### Create Release PR and Publish Release (No Config)

Source: https://releasaurus.rgon.io/

Use these commands for a zero-configuration release workflow. First, create a release pull request, then publish the release after merging.

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

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

--------------------------------

### Enable Automatic Next Version Bumping

Source: https://releasaurus.rgon.io/print.html

Configure `auto_start_next` globally or per-package to automatically bump versions after a release.

```toml
__
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)


```

--------------------------------

### Use GitLab Token with Releasaurus

Source: https://releasaurus.rgon.io/print.html

Examples of using Releasaurus with the GITLAB_TOKEN environment variable for both GitLab.com and self-hosted GitLab instances.

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

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

--------------------------------

### Project Structure with Configuration File

Source: https://releasaurus.rgon.io/configuration.html

Illustrates the placement of the `releasaurus.toml` configuration file within a project's root directory.

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

```

--------------------------------

### Stable Release with Aggregated Prereleases

Source: https://releasaurus.rgon.io/print.html

Shows how to create a stable release that includes changelog entries from all prior prerelease versions by enabling `aggregate_prereleases`.

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


```

```toml
__
[changelog]
aggregate_prereleases = true


```

--------------------------------

### Testing with a Local Repository

Source: https://releasaurus.rgon.io/contributing.html

Simulate a release process using a local directory as the target repository. This is helpful for debugging the release-pr command without affecting remote repositories.

```bash
just run release-pr \
  --forge local \
  --repo "/path/to/test/project" \
  --debug
```

--------------------------------

### Node.js Package Release Phases

Source: https://releasaurus.rgon.io/configuration-prerelease.html

Illustrates how to manage release phases for a Node.js package by commenting and uncommenting prerelease configurations.

```toml
# 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
```

--------------------------------

### Get All Current Releases

Source: https://releasaurus.rgon.io/print.html

Retrieve information about the most recent release for each package as a JSON array. This command is useful for inspecting the current state of releases across your project.

```bash
releasaurus get current-release \
  --forge github \
  --repo "https://github.com/owner/repo"
```

--------------------------------

### After Editing Release Notes

Source: https://releasaurus.rgon.io/release-notes-editing.html

This demonstrates how to add custom release notes directly into the notes `<div>`. The added text appears between the metadata and the package version header.

```html
<div id="my-package" data-tag="v1.2.3">
<!--{"metadata":{"sha_compare_link":"...","tag_compare_link":"..."}}-->

## [v1.2.3](...) - 2026-04-10

This release improves startup performance and fixes a crash on
empty input. See the [migration guide](https://example.com) for
details.

### Features
- feat: some new feature (abc1234)
</div>
```

--------------------------------

### Override global auto_start_next setting for a package

Source: https://releasaurus.rgon.io/print.html

Set `auto_start_next` to `false` for a specific package to disable automatic starting of the next version for that package, overriding the global setting.

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

```

--------------------------------

### Add Additional Manifest Files (Mixed Format)

Source: https://releasaurus.rgon.io/configuration-reference.html

Combine simple string paths (using default regex) and custom objects with `version_regex` for updating version strings in various files.

```toml
__
[[package]]
path = "."
release_type = "rust"
additional_manifest_files = [
    "VERSION",                    # Uses default regex
    "README.md",                  # Uses default regex
    { path = "config.yml", version_regex = "app_version:\s*(?<version>\d+\.\d+\.\d+)" }
]


```

--------------------------------

### Configure Automatic Version Bumping

Source: https://releasaurus.rgon.io/configuration-monorepo.html

Set `auto_start_next` to `true` globally to automatically bump versions after a release. Individual packages can override this setting.

```toml
__
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)

```

--------------------------------

### Get Current Release for a Specific Package

Source: https://releasaurus.rgon.io/print.html

Query information about the most recent release for a specific package. This command returns details about the last published release for the targeted package.

```bash
releasaurus get current-release \
  --package my-pkg \
  --forge github \
  --repo "https://github.com/owner/repo"
```

--------------------------------

### Versioned Strategy: Graduating to Stable

Source: https://releasaurus.rgon.io/configuration-prerelease.html

To graduate to a stable release from a prerelease, remove the prerelease section or set suffix to an empty string.

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

```

--------------------------------

### Get Current Release Information

Source: https://releasaurus.rgon.io/commands.html

Retrieves information about the most recent release for each package. Useful for checking deployed versions or comparing current releases across packages in a monorepo.

```APIDOC
## releasaurus get current-release

### Description
Returns information about the most recent release for each package. Packages without releases are omitted from the output.

### Method
CLI Command

### Parameters
#### Path Parameters
None

#### Query Parameters
- `--package` (string) - Optional - Filter results to a specific package.
- `--forge` (string) - Required - The forge to use (e.g., github).
- `--repo` (string) - Required - The repository URL.
- `--out-file` (string) - Optional - Path to save the output JSON file.

### Request Example
```bash
# Get all current releases
releasaurus get current-release \
  --forge github \
  --repo "https://github.com/owner/repo"

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

# Write to file
releasaurus get current-release \
  --out-file current.json \
  --forge github \
  --repo "https://github.com/owner/repo"
```

### Response
#### Success Response (200)
JSON array of release objects. Packages without releases are omitted.
```

--------------------------------

### Specify Additional Manifest Files (Mixed Format)

Source: https://releasaurus.rgon.io/print.html

Combine simple string paths with custom regex configurations for additional manifest files. Files without a matching pattern are skipped.

```toml
__
[[package]]
path = "."
release_type = "rust"
additional_manifest_files = [
    "VERSION",                    # Uses default regex
    "README.md",                  # Uses default regex
    { path = "config.yml", version_regex = "app_version:\s*(?<version>\d+\.\d+\.\d+)" }
]

```

--------------------------------

### Implement Custom Forge Trait

Source: https://releasaurus.rgon.io/print.html

Implement the `Forge` trait from `releasaurus_core::forge::traits` to target a custom platform. This example shows a basic structure for a custom Forge implementation.

```rust
#![allow(unused)]
fn main() {
use async_trait::async_trait;
use releasaurus_core::{
    config::Config,
    forge::{
        request::Tag,
        request::(
            Commit, CreateCommitRequest, CreatePrRequest,
            CreateReleaseBranchRequest, ForgeCommit,
            GetFileContentRequest, GetPrRequest, PrLabelsRequest,
            PullRequest, ReleaseByTagResponse, UpdatePrRequest,
        ),
        traits::Forge,
    },
    result::Result,
};
use std::any::Any;
use url::Url;

pub struct MyForge { /* ... */ }

#[async_trait]
impl Forge for MyForge {
    fn repo_name(&self) -> String { todo!() }
    fn release_link_base_url(&self) -> Url { todo!() }
    fn compare_link_base_url(&self) -> Url { todo!() }
    fn default_branch(&self) -> String { todo!() }

    async fn load_config(
        &self,
        branch: Option<String>,
    ) -> Result<Config> { todo!() }

    async fn get_file_content(
        &self,
        req: GetFileContentRequest,
    ) -> Result<Option<String>> { todo!() }

    // ... remaining trait methods
    async fn get_release_by_tag(&self, _: &str)
        -> Result<ReleaseByTagResponse> { todo!() }
    async fn create_release_branch(&self, _: CreateReleaseBranchRequest)
        -> Result<Commit> { todo!() }
    async async fn create_commit(&self, _: CreateCommitRequest)
        -> Result<Commit> { todo!() }
    async fn tag_commit(&self, _: &str, _: &str)
        -> Result<()> { todo!() }
    async fn get_latest_tags_for_prefix(&self, _: &str, _: &str)
        -> Result<Vec<Tag>> { todo!() }
    async fn get_commits(&self, _: Option<String>, _: Option<String>)
        -> Result<Vec<ForgeCommit>> { todo!() }
    async fn get_open_release_pr(&self, _: GetPrRequest)
        -> Result<Option<PullRequest>> { todo!() }
    async fn get_merged_release_pr(&self, _: GetPrRequest)
        -> Result<Option<PullRequest>> { todo!() }
    async fn create_pr(&self, _: CreatePrRequest)
        -> Result<PullRequest> { todo!() }
    async fn update_pr(&self, _: UpdatePrRequest)
        -> Result<()> { todo!() }
    async fn replace_pr_labels(&self, _: PrLabelsRequest)
        -> Result<()> { todo!() }
    async fn create_release(&self, _: &str, _: &str, _: &str)
        -> Result<()> { todo!() }
}
}
```

--------------------------------

### Use Releasaurus Dry Run Mode

Source: https://releasaurus.rgon.io/print.html

Examples of enabling dry-run mode for Releasaurus using the RELEASAURUS_DRY_RUN environment variable. Dry-run mode automatically enables debug mode.

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

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

--------------------------------

### Test Beta Prereleases via CLI

Source: https://releasaurus.rgon.io/configuration-prerelease.html

Use the `releasaurus release-pr` command to test beta prereleases with a specified suffix and strategy.

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

--------------------------------

### Get Release Data

Source: https://releasaurus.rgon.io/print.html

Retrieves detailed release data for a specific tag, including tag name, commit SHA, and release notes. Can output directly or save to a file.

```bash
releasaurus get release \
  --tag v1.0.0 \
  --forge github \
  --repo "https://github.com/owner/repo"
```

```bash
releasaurus get release \
  --tag v1.0.0 \
  --out-file release.json \
  --forge github \
  --repo "https://github.com/owner/repo"
```

--------------------------------

### Write Projected Releases to File

Source: https://releasaurus.rgon.io/print.html

Get projected next release information and write the JSON output to a specified file. This is useful for processing release data with other tools or for record-keeping.

```bash
releasaurus get next-release \
  --out-file releases.json \
  --forge github \
  --repo "https://github.com/owner/repo"
```

--------------------------------

### Provide API Token via Command Line

Source: https://releasaurus.rgon.io/commands.html

Authenticate API requests by providing your access token directly as a command-line argument.

```bash
--token "your_token_here"
```

--------------------------------

### Get Projected Next Release Information

Source: https://releasaurus.rgon.io/commands.html

Retrieves projected next release information as JSON. Useful for debugging configuration and troubleshooting version detection. Output can be written to a file.

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

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

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

```bash
# Test locally
releasaurus get next-release --forge local --repo "."
```

--------------------------------

### Running Tests for Your Language

Source: https://releasaurus.rgon.io/print.html

Use the `just test` command to run all tests for a specific language or module. The `release-pr` command can be used for testing with real repositories, with options for local or remote forges and dry runs.

```bash
# Run all tests for your language
just test yourlanguage

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

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

# Test with real remote forge and local path to clone
just run release-pr \
  --forge github \
  --repo "https://github.com/your/repo" \
  --local-path "/path/to/your/repo" \
  --debug \
  --dry-run
```

--------------------------------

### Example Release Notes Structure in PR Body

Source: https://releasaurus.rgon.io/release-notes-editing.html

This is the default structure rendered by `release-pr` for a package's release notes within a pull request. It includes metadata and release details.

```html
<details open>
<summary>v1.2.3</summary>
<div id="my-package-header"></div>
<div id="my-package" data-tag="v1.2.3">
<!--{"metadata":{"sha_compare_link":"...","tag_compare_link":"..."}}-->

## [v1.2.3](...) - 2026-04-10
### Features
- feat: some new feature (abc1234)
</div>
<div id="my-package-footer"></div>
</details>
```

--------------------------------

### CLI Overrides for Prerelease Settings

Source: https://releasaurus.rgon.io/print.html

Demonstrates how to override global and package-specific prerelease settings directly from the command line for testing or temporary adjustments.

```bash
__
# 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"


```

--------------------------------

### Get All Projected Releases

Source: https://releasaurus.rgon.io/print.html

Retrieve projected next release information for all packages as a JSON array. This is useful for inspecting potential releases, debugging configuration, and generating custom notification scripts.

```bash
releasaurus get next-release \
  --forge github \
  --repo "https://github.com/owner/repo"
```

--------------------------------

### Get Next Release Information

Source: https://releasaurus.rgon.io/commands.html

Retrieves projected next release information for packages. This is useful for inspecting upcoming releases, debugging version detection, and generating custom notification scripts.

```APIDOC
## releasaurus get next-release

### Description
Returns projected next release information as JSON. Identifies packages that have been previously tagged, analyzes their current versions, bumps the patch version, and prepares manifest updates.

### Method
CLI Command

### Parameters
#### Path Parameters
None

#### Query Parameters
- `--package` (string) - Optional - Filter results to a specific package.
- `--forge` (string) - Required - The forge to use (e.g., github).
- `--repo` (string) - Required - The repository URL.
- `--out-file` (string) - Optional - Path to save the output JSON file.

### Request Example
```bash
# Get all projected releases
releasaurus get next-release \
  --forge github \
  --repo "https://github.com/owner/repo"

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

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

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

### Response
#### Success Response (200)
JSON array of releasable packages with version, commits, and notes.
```

--------------------------------

### Typical Local Repository Testing Workflow

Source: https://releasaurus.rgon.io/print.html

This workflow demonstrates modifying `releasaurus.toml`, testing the changes locally, reviewing logs, committing configuration updates, and finally running against the remote forge.

```bash
# 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"
```

--------------------------------

### Get Release Data for Existing Tag

Source: https://releasaurus.rgon.io/commands.html

Retrieves release data for a specific existing tag, including the tag name, commit SHA, and release notes. The output is a JSON object.

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

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

--------------------------------

### Get Current Release Information

Source: https://releasaurus.rgon.io/commands.html

Returns information about the most recent release for each package. Packages without releases are omitted. Use this to check deployed versions or compare releases across packages.

```bash
# Get all current releases
releasaurus get current-release \
  --forge github \
  --repo "https://github.com/owner/repo"
```

```bash
# Filter to specific package
releasaurus get current-release \
  --package my-pkg \
  --forge github \
  --repo "https://github.com/owner/repo"
```

```bash
# Write to file
releasaurus get current-release \
  --out-file current.json \
  --forge github \
  --repo "https://github.com/owner/repo"
```

--------------------------------

### Typical Local Testing Workflow

Source: https://releasaurus.rgon.io/commands.html

A common workflow for testing local configuration changes involves editing the `releasaurus.toml` file, then running a local test with `release-pr`, and finally reviewing the generated logs.

```bash
# 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
```

--------------------------------

### GitLab CI Release Pull Request

Source: https://releasaurus.rgon.io/ci-cd-integration.html

Create release pull requests in GitLab CI using the Releasaurus Docker image. This example demonstrates using a custom variable for token authentication.

```yaml
release-pr:
  image:
    name: rgonnella/releasaurus:vX.X.X
    entrypoint: [""]
  script:
    # Uses custom var for token authentication
    - releasaurus release-pr --forge gitlab \
        --repo $CI_PROJECT_URL --token $RELEASE_TOKEN
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
```

--------------------------------

### Forge Platform Configuration

Source: https://releasaurus.rgon.io/print.html

Demonstrates how to specify the Git forge platform and repository URL for Releasaurus commands. Supports GitHub, GitLab, Gitea (and Forgejo), and local repositories for testing.

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

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

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

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

--------------------------------

### Get Release Data by Tag

Source: https://releasaurus.rgon.io/commands.html

Retrieves release data for a specific existing tag, including the tag name, commit SHA, and release notes. Useful for inspecting historical release details.

```APIDOC
## releasaurus get release

### Description
Retrieves release data for an existing tag, including the tag name, commit SHA, and release notes.

### Method
CLI Command

### Parameters
#### Path Parameters
None

#### Query Parameters
- `--tag` (string) - Required - The release tag name.
- `--forge` (string) - Required - The forge to use (e.g., github).
- `--repo` (string) - Required - The repository URL.
- `--out-file` (string) - Optional - Path to save the output JSON file.

### Request Example
```bash
# Display release notes
releasaurus get release \
  --tag v1.0.0 \
  --forge github \
  --repo "https://github.com/owner/repo"

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

### Response
#### Success Response (200)
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
```

--------------------------------

### Release PR and Release Commands with Package Targeting

Source: https://releasaurus.rgon.io/print.html

Shows how to use `--package` flag with `release-pr` and `release` commands to target specific packages for release.

```bash
# Create a release PR for just the API package
releasaurus release-pr \
  --package api \
  --forge github \
  --repo "https://github.com/owner/repo"

# Publish a release for just the API package
releasaurus release \
  --package api \
  --forge github \
  --repo "https://github.com/owner/repo"


```

--------------------------------

### Run Unit Tests

Source: https://releasaurus.rgon.io/contributing.html

Execute unit tests to verify individual components without external dependencies. Use 'just test-cov' for coverage reports.

```bash
# run unit tests
just test
# run unit tests with coverage
just test-cov
```

--------------------------------

### Use GitHub Token with Releasaurus

Source: https://releasaurus.rgon.io/print.html

Demonstrates how to use Releasaurus with the GITHUB_TOKEN environment variable set. Alternatively, the token can be provided directly via the --token flag, though this is less secure.

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

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

--------------------------------

### Combine Multiple Prerelease Overrides

Source: https://releasaurus.rgon.io/commands.html

Apply multiple overrides simultaneously, including base branch, global suffix, and package-specific settings.

```bash
releasaurus release-pr \
  --base-branch staging \
  --prerelease-suffix alpha \
  --set-package frontend.prerelease.suffix=beta \
  --forge github \
  --repo "https://github.com/owner/repo"
```

--------------------------------

### Construct RepoUrl for Forge

Source: https://releasaurus.rgon.io/library-api.html

Example of constructing a RepoUrl struct, used by forge constructors like Github::new. The 'path' field should reflect the full project path, especially for nested GitLab groups.

```rust
#![allow(unused)]
fn main() {
use releasaurus_core::forge::{RepoUrl, config::Scheme};

let url = RepoUrl {
    scheme: Scheme::Https,
    host: "github.com".into(),
    owner: "my-org".into(),
    name: "my-repo".into(),
    // Full project path — for nested GitLab groups this may be
    // "group/subgroup/repo"
    path: "my-org/my-repo".into(),
    port: None,
    token: None,
};
}

```
Tokens:
Raw