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:

Releasaurus installed - See Installation if you haven't already
A Git repository with some commits to release
Access token for your Git forge platform (GitHub, GitLab, or Gitea)
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

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

GitLab

Go to GitLab User Settings → Access Tokens
Create a token with these scopes:
- api
- read_repository
- write_repository

Gitea

Go to your Gitea instance → User Settings → Applications
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:

Analyze your commits since the last release using conventional commit patterns
Determine the next version based on the changes (patch, minor, or major)
Update version files in your project automatically
Generate a changelog from your commit history
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.

Review the pull request that was created
Check the changelog and version updates
Make any necessary adjustments by pushing additional commits to the PR branch
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:

Create a Git tag for the new version
Push the tag to your repository
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:

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

Next Steps

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

Configuration - Customization options and advanced setup
Troubleshooting - Common issues and solutions

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:

Push commits using conventional commit format to your main branch
GitHub Action automatically creates a release PR with version updates and changelog
Review and merge the PR when ready
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.

Keyboard shortcuts

Releasaurus