innoday-blastoff

A small CLI to batch GitHub releases and hotfixes across multiple repositories grouped by a GitHub topic.

blastoff computes the next semantic version for a group of repos, tags every repository that carries a given GitHub topic, generates a per-repo changelog of merged pull requests, and (optionally) a Claude-authored release summary. Hotfixes bump the patch version, with two supported modes.

• Install / distribution name: innoday-blastoff (on PyPI)
• Import / command name: blastoff

What it does

• Batch releases by topic — point it at a GitHub org and a topic; it finds every repo carrying that topic and creates the same release tag on each (skipping archived repos and repos that already have the tag).
• Automatic version computation — the next version is resolved from a local config by alias, so you don't hand-type tags. A release bumps the minor version; a hotfix bumps the patch.
• Changelog generation — collects merged PRs across all matched repos since the last release/hotfix and writes a structured per-repo changelog to CHANGELOG.md.
• Optional Claude release summary — when a Claude API key is available, an executive-facing narrative of the release is generated; otherwise blastoff falls back to PR titles.
• Dry run by default — every release/hotfix is a preview unless you add --release.
• Pluggable version backend — release state lives in a local file by default, but you can implement your own VersionStore to keep it anywhere (see Extending).

Install

With pip:

pip install innoday-blastoff

With uv:

uv pip install innoday-blastoff
# or add it to a project
uv add innoday-blastoff

The distribution is named innoday-blastoff, but the CLI and the import package are both blastoff:

blastoff --help            # the CLI is on PATH after install
python -c "import blastoff" # import by package name

Prerequisites

blastoff talks to the GitHub API and, optionally, to Claude. Configure it with environment variables (a .env file in the working directory is loaded automatically):

* GH_ORG and TOPIC can also be supplied per-invocation via CLI flags, or resolved from config by alias (see below). When you resolve a release by alias (-c <alias>), the org and topic come from the config entry and you don't need the env vars.

Usage

blastoff has four subcommands: release, hotfix, summarize, and version.

Releases

The version and topic are resolved from config by alias. Do not pass -t/--tag for a topic/alias release — the tag is computed for you from the config's next_version. Passing -t is a one-off override that bypasses config resolution and never mutates stored version state.

# Dry run — shows what would be released, writes nothing (safe to run anytime)
blastoff release -c <alias>

# Actually create the releases
blastoff release -c <alias> --release

# Release only a single repository
blastoff release -c <alias> --repo <repo-name> --release

Useful flags:

• --release / -r — perform the release. Omitting it is always a dry run.
• --repo <name> — restrict to a single repository.
• --summary "text" — use this text verbatim as the release summary instead of auto-generating one.
• --changelog-output <path> — where to write the changelog (default: CHANGELOG.md).
• -o/--org, -k/--token, -c/--topic — override GH_ORG, GH_TOKEN, TOPIC.

On a real release, blastoff validates the token, creates the tag on each matching repo, writes the changelog, bumps the stored next_version (minor bump), and records the released version via the configured backend.

Hotfixes

Hotfixes bump the patch version from the last released version. Two modes are supported per alias (set with the hotfix_mode field in config):

blastoff scans existing GitHub releases in the topic to pick the next free hotfix number, so re-runs are safe.

# Dry run
blastoff hotfix -c <alias>

# Create the hotfix releases
blastoff hotfix -c <alias> --release

# Hotfix a single repo
blastoff hotfix -c <alias> --repo <repo-name> --release

# Hotfix a single repo at a specific commit
blastoff hotfix -c <alias> --repo <repo-name> --commit <sha> --release

A full release must have run first (the hotfix base is the config's last_released_version).

Summaries

summarize produces a Markdown release document (written to releases/ by default):

blastoff summarize                       # all configured aliases
blastoff summarize --alias <alias>       # a single alias
blastoff summarize --output-dir <path>   # custom output directory

Version config

version inspects the resolved config:

blastoff version print   # show the version state for all configured aliases
blastoff version check   # validate the config and report any errors

Configuration

Version and release state is read from a local file. blastoff looks for two sources, in order, walking up from the current directory:

1. .innoday/project.yml — a project config file blastoff reads if present. Add a release_configs list to it (this is optional; it exists so blastoff can share a project's config file rather than requiring a separate one).
2. org-versions.json — the standalone fallback, holding local per-machine release state.

The resolution logic lives in blastoff/config_loader.py, and the default file backend is blastoff/stores/file_store.py.

org-versions.json

Create it in your project root (or any parent directory), with one entry per alias:

{
  "organizations": [
    {
      "alias": "my-app",
      "organization": "my-github-org",
      "label": "my-release-topic",
      "next_version": "v1.2.0",
      "prerelease": null,
      "last_released": null,
      "last_released_version": null,
      "last_hotfix": null,
      "hotfix_mode": "increment"
    }
  ]
}

Field reference:

After a successful release or hotfix, whichever source the config was loaded from is updated automatically with the new version state.

.innoday/project.yml — release_configs

If you keep a .innoday/project.yml, blastoff will read a release_configs list from it (checked before org-versions.json), with the same fields per alias:

release_configs:
  - alias: my-app
    organization: my-github-org
    label: my-release-topic
    next_version: v1.2.0
    prerelease: null
    last_released: null
    last_released_version: null
    last_hotfix: null
    hotfix_mode: increment

Extending — custom version backends

Where release state lives is pluggable. blastoff computes versions and tags repos; where the version state is loaded from and where a completed release is recorded is abstracted behind the VersionStore interface (blastoff.stores.VersionStore). The shipped default is FileVersionStore (the file-backed backend above).

To store release state somewhere else — a database, an internal API, a service — implement the three abstract methods and inject your store into the release/hotfix commands:

from blastoff.stores import VersionStore
from blastoff.version_manager import OrgConfig


class MyVersionStore(VersionStore):
    def load_org_config(self, alias: str) -> OrgConfig:
        """Return the OrgConfig for `alias` (raise FileNotFoundError if none)."""
        ...

    def save_org_config(self, org: OrgConfig) -> None:
        """Persist an updated OrgConfig back to your backend."""
        ...

    def record_release(self, org, version, released_at=None, summary=None, changelog=None) -> None:
        """Record that `version` was released for `org` (called after tagging)."""
        ...

Both the Release and Hotfix commands expose a version_store attribute; set it before invoking to swap the backend. When left unset it defaults to FileVersionStore, giving you the standalone file-backed behavior described above. blastoff imports nothing from any consumer — the dependency arrow points one way: your code depends on blastoff and implements this interface.

Testing

uv run pytest

The suite is hermetic — no network access required.

Contributing

Contributions are welcome. See CONTRIBUTING.md for setup, the lint conventions, and the behavioral contracts (dry-run-by-default, idempotent re-runs, the VersionStore interface) that are easy to break by accident.

Security

blastoff holds a GitHub token with repo scope and can create tags and releases across every repository carrying a topic. Please report vulnerabilities privately rather than in a public issue — see SECURITY.md, which also documents the threat model and what is in scope.

Changelog

See CHANGELOG.md.

Renamed: this package was published as pixelfuel-blastoff for 0.1.0. It is now innoday-blastoff (a separate PyPI project, since PyPI has no rename); the old distribution is yanked. The import package and CLI command are unchanged — both are still blastoff.

License

MIT — see LICENSE.

To publish a new version to PyPI, see PUBLISHING.md.