releasio¶

Automated releases for Python projects
Version bumping, changelog generation, and PyPI publishing powered by conventional commits

Get Started View on GitHub

Features¶

Release PR Workflow

Automatically creates and maintains release PRs with version bumps and changelogs. Merge to release.

Learn more
Conventional Commits

Automatic version bumping based on commit types. feat: bumps minor, fix: bumps patch, ! bumps major.

Commit format
Beautiful Changelogs

Professional changelog generation with built-in native generator or git-cliff. PR links, author attribution, and customizable templates.

Changelog guide
Zero Configuration

Works out of the box with sensible defaults. Just run releasio check to see what would happen.

Configuration
GitHub Actions

Native GitHub Actions support with trusted publishing (OIDC). No API tokens required for PyPI.

Actions setup
PyPI Publishing

Build and publish to PyPI with uv, poetry, pdm, or twine. Supports trusted publishing and private registries.

Publishing guide

How It Works¶

%%{init: {'theme': 'neutral'}}%%
graph LR
    A[Push to main] --> B[releasio release-pr]
    B --> C[Release PR Created]
    C --> D[Merge PR]
    D --> E[releasio release]
    E --> F[GitHub Release + PyPI]

Push commits to your main branch using conventional commit messages
releasio release-pr automatically creates a release PR with:
- Version bump based on commit types
- Updated changelog
- All changes ready to review
Merge the PR to trigger the release
releasio release creates a GitHub release and publishes to PyPI

Quick Start¶

Installation¶

pip install releasio

Optional: git-cliff

For advanced changelog customization, install git-cliff. releasio works out of the box with its built-in native changelog generator.

Preview a Release¶

releasio check

This shows what would happen without making any changes:

The calculated next version
Commits that would be included
Changelog preview

Create a Release PR¶

releasio release-pr --execute

Creates or updates a release PR with version bump and changelog.

Full Release¶

releasio do-release --execute

Does everything in one command: updates version, generates changelog, commits, tags, and publishes.

Full getting started guide

Version Bumping Rules¶

releasio follows Semantic Versioning with automatic detection:

Commit Type	Version Bump	Example
`feat:`	Minor (0.1.0 → 0.2.0)	`feat: add new feature`
`fix:`	Patch (0.1.0 → 0.1.1)	`fix: resolve bug`
`feat!:` or `BREAKING CHANGE:`	Major (0.1.0 → 1.0.0)	`feat!: redesign API`
`docs:`, `chore:`, etc.	Patch	`docs: update readme`

Pre-1.0.0 Behavior

Before version 1.0.0, breaking changes bump minor instead of major, following common semver conventions for unstable APIs.

GitHub Actions Integration¶

Minimal WorkflowManual Release

name: Release

on:
  push:
    branches: [main]

permissions:
  contents: write
  pull-requests: write
  id-token: write

jobs:
  release-pr:
    if: "!startsWith(github.event.head_commit.message, 'chore(release):')"
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: mikeleppane/releasio@v2
        with:
          command: release-pr
          github-token: ${{ secrets.GITHUB_TOKEN }}

  release:
    if: startsWith(github.event.head_commit.message, 'chore(release):')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: mikeleppane/releasio@v2
        with:
          command: release
          github-token: ${{ secrets.GITHUB_TOKEN }}

name: Release

on:
  workflow_dispatch:
    inputs:
      command:
        type: choice
        options: [check, release-pr, do-release]
      execute:
        type: boolean
        default: false

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: mikeleppane/releasio@v2
        with:
          command: ${{ inputs.command }}
          execute: ${{ inputs.execute }}
          github-token: ${{ secrets.GITHUB_TOKEN }}

Complete GitHub Actions guide

Configuration¶

releasio works with zero configuration, but you can customize everything:

.releasio.tomlpyproject.toml

default_branch = "main"

[version]
tag_prefix = "v"

[changelog]
path = "CHANGELOG.md"

[commits]
types_minor = ["feat"]
types_patch = ["fix", "perf", "docs"]

[github]
release_pr_branch = "release"
release_pr_labels = ["release"]

[publish]
tool = "uv"

[tool.releasio]
default_branch = "main"

[tool.releasio.version]
tag_prefix = "v"

[tool.releasio.changelog]
path = "CHANGELOG.md"

Full configuration reference