releaser

Warning

This project is archived and no longer maintained.

Release automation has moved to Google Release Please. Reusable Telegram pull request and issue notification workflows have moved to rubykatzen/baseline: notify-telegram-pr-shared.yml and notify-telegram-issue-shared.yml.

Existing consumers should migrate away from Releaser workflows and actions.

releaser is an opinionated zero-config release orchestrator for GitHub repositories.

It verifies that origin/main is releasable (new commits, CI green or recoverable), dispatches protecting workflows when needed, runs prepare-release.yml, opens a release/vX.Y.Z PR, merges it, and waits until publish-release.yml creates the annotated tag and GitHub Release.

Usage

Check release readiness:

releaser status
releaser status --verbose   # includes per-check CI details

Cut a full release (version calculated automatically; waits until published):

releaser patch
releaser minor
releaser major

Open a release PR and stop (merge manually later):

releaser patch --pr-only

Cut a release with an explicit version:

releaser cut 1.2.3

Dry-run without triggering anything:

releaser patch --dry-run

Check local tooling:

releaser doctor

Machine-readable output:

releaser status --json
releaser patch --dry-run --json

How it works

1. Fetches origin/main and finds the latest SemVer tag.
2. Checks that there are new commits since that tag and lists them in status.
3. Queries GitHub branch protection to find required CI checks.
4. If required checks are missing on the origin/main SHA, dispatches {check}.yml workflows (zero-config convention) and waits until they pass.
5. Dispatches prepare-release.yml with the computed version and base_sha.
6. Watches the workflow run; aborts if it fails.
7. Opens a PR from release/vX.Y.Z → main.
8. Unless --pr-only: merges the PR (auto-merge when the repo allows it, otherwise waits for PR checks and merges directly), watches publish-release.yml, and verifies the tag and GitHub Release exist.

Contract

• Run from inside the target git repository.
• Release source is origin/main, not local HEAD.
• Local dirty worktrees do not block releases.
• Release tags use vMAJOR.MINOR.PATCH and are annotated.
• GitHub Actions must have successful check runs for the origin/main SHA (protecting workflows must expose workflow_dispatch and use job names matching branch-protection contexts, e.g. check lint → lint.yml).
• The repository must provide prepare-release.yml (triggered by workflow dispatch) and publish-release.yml (triggered by merged release/* PRs).
• GitHub Releases are created by publish-release.yml, not by the CLI.

Reusable Actions

releaser ships composite actions that can be used in any repo's publish-release.yml to publish packages to the relevant target.

Homebrew tap update

Updates all formulas in the checked-out tap to the latest upstream release.

- uses: rubykatzen/releaser/.github/actions/update-homebrew-formulas@vX.Y.Z
  with:
    token: ${{ secrets.GITHUB_TOKEN }}  # optional, defaults to github.token

Publish to RubyGems

Builds and pushes a Ruby gem. Auto-detects the .gemspec in the repo root.

- uses: rubykatzen/releaser/.github/actions/publish-rubygems@vX.Y.Z
  with:
    api-key: ${{ secrets.RUBYGEMS_API_KEY }}
    # ruby-version: "3.2"        # optional, default: 3.2
    # gemspec: path/to/my.gemspec  # optional, auto-detected

Publish to PyPI

Builds a Python distribution (python -m build) and uploads it to PyPI using an API token.

- uses: rubykatzen/releaser/.github/actions/publish-pypi@vX.Y.Z
  with:
    pypi-token: ${{ secrets.PYPI_TOKEN }}
    # python-version: "3.12"  # optional, default: 3.12

Releasing

releaser releases itself. Run from inside this repository:

releaser patch   # or: releaser minor / releaser major

Check readiness without triggering anything:

releaser status
releaser patch --dry-run

prepare-release.yml fires on dispatch, creates the release/vX.Y.Z branch, generates AI release notes, bumps pyproject.toml, and pushes the branch. By default the CLI then merges the PR and waits for publish-release.yml. Use --pr-only to stop after opening the PR.

Installation

brew tap rubykatzen/tap
brew trust rubykatzen/tap
brew install releaser

Upgrade with:

brew update && brew upgrade releaser

Requirements

• git
• GitHub CLI (gh) installed and authenticated
• A GitHub repository with origin/main
• prepare-release.yml workflow (workflow dispatch, fields: version, base_sha)
• publish-release.yml workflow (triggers on merged release/* PRs)

Exit Codes

Code	Meaning
0	Success
1	Release is not allowed
2	Usage error
3	Environment error
4	External command failed