ReleaseKit

Versioning, changelogs, and publishing for whatever you ship — driven by Conventional Commits, built for CI.

Why · Quickstart · Packages · Docs · Contributing

Releases to npm, crates.io, and pub.dev today, with more ecosystems on the way.

   from Conventional Commits:

   ┌─────────┐     ┌─────────┐     ┌─────────┐
   │ version │ ──▶ │  notes  │ ──▶ │ publish │
   └─────────┘     └─────────┘     └─────────┘
    semver bumps    changelog +     npm · crates.io · pub.dev
    per package     LLM notes       git tags · GitHub Release

   Independent CLIs, piped via a VersionOutput JSON contract — run one stage or all three.

Warning

🚧 Pre-1.0.0 — here be dragons 🐉

ReleaseKit is under active development and evolving fast while the core feature set settles.

💥 Breaking changes are common between releases and won't be gated behind a major bump while we're pre-1.0.0. It's not recommended for production yet — if you're trying it out, pin an exact version and skim the release notes before upgrading.

Once the API stabilises, v1.0.0 will mark the switch to semver-stable guarantees.

Why ReleaseKit

• One config, every ecosystem — npm (JavaScript/TypeScript), crates.io (Rust), and pub.dev (Dart/Flutter) packages release from the same releasekit.config.json, including mixed monorepos. The pipeline is registry-agnostic — new ecosystems plug in without changing your workflow.
• Composable, not opinionated — three independent CLIs (version, notes, publish) you can pipe together, or a unified release command if you want the full pipeline.
• CI-native — JSON output, OIDC publishing, PR preview comments, and label- or commit-driven triggers without bolting on extra tools.

Coming from semantic-release or changesets? See the Migration guide for a mapping of concepts and a step-by-step switch.

Quickstart

npm:

npm install -g @releasekit/release

pnpm:

pnpm add -g @releasekit/release

Then:

releasekit init
releasekit release --dry-run

Running version analysis...
Found 2 package update(s)
  @myorg/core → 1.4.0
  @myorg/ui   → 1.4.0
Generating release notes...
Publishing... (dry-run, no packages published)

See Getting Started for prerequisites, config options, and a first real release.

Packages

All four packages share a single version (sync versioning) — see the version badge above.

Package	Downloads	Description
@releasekit/release		Unified CLI — run version, notes, and publish in a single command
@releasekit/version		Semantic versioning based on Git history and conventional commits
@releasekit/notes		Changelog generation with LLM-powered enhancement and flexible templating
@releasekit/publish		Publish packages to npm, crates.io, and pub.dev with git tagging and GitHub releases

Features

• 🔖 Versioning — derives semver bumps from Conventional Commits; supports JavaScript/TypeScript (package.json), Rust (Cargo.toml), Dart/Flutter (pubspec.yaml), and monorepos with per-package tags
• 📝 Release notes — generates changelogs from commit history, with optional LLM enhancement (Anthropic, OpenAI, or local models)
• 📦 Publishing — pushes to npm (OIDC or token), crates.io, and pub.dev, tags the release, and creates a GitHub Release
• ⚙️ CI/CD first — JSON output for scripting, PR preview comments, and config-driven triggers (commit vs label)
• 🧩 Composable — use each tool independently or pipe them together

Usage

releasekit release --dry-run
releasekit release
releasekit release --skip-notes
releasekit release --bump patch

Each step is also a subcommand — releasekit version, releasekit notes, releasekit publish — and the underlying tools (releasekit-version, releasekit-notes, releasekit-publish) can be piped together. See the package docs for the full CLI reference.

GitHub Action

Use ReleaseKit as a composite action with release or preview modes:

jobs:
  release:
    permissions:
      id-token: write
      contents: write
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0
      - uses: goosewobbler/releasekit@v0
        with:
          mode: release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

See docs/action.md for the preview mode, full input/output reference, and rollout guidance.

Configuration

ReleaseKit reads releasekit.config.json or releasekit.config.jsonc (comments and trailing commas supported) at the project root. All configuration is optional — sensible defaults apply. A typical config:

{
  "$schema": "https://goosewobbler.github.io/releasekit/schema.json",
  "notes": {
    "changelog": { "mode": "root" }
  },
  "publish": {
    "npm": { "enabled": true, "access": "public" }
  }
}

See the package docs for the full option reference.

Documentation

Guides

• Getting Started — install, first dry run, first release, CI setup
• Architecture — pipeline design, mental model, release strategies
• CI setup — GitHub Actions workflows, OIDC, PR preview, prerelease
• CI examples — runnable, CI-validated workflow + config scenarios (minimal, label-driven, standing-PR, OIDC, monorepo-rust, prerelease)
• Rust / Cargo — Rust crate versioning and crates.io publishing
• Dart / pub.dev — Dart/Flutter versioning and pub.dev publishing
• Migration — from semantic-release or changesets

Reference

• CLI — every command and flag for the releasekit CLI
• Configuration — full config reference (all releasekit.config.json options)
• GitHub Action — goosewobbler/releasekit action inputs, outputs, and rollout
• @releasekit/release — unified pipeline, CI automation, programmatic API
• @releasekit/version — versioning strategies, JSON output
• @releasekit/notes — changelog, release notes, LLM, templates
• @releasekit/publish — npm, crates.io, pub.dev, GitHub Releases

Help

• Troubleshooting — symptom-indexed error guide
• LLM providers — OpenAI, Anthropic, Ollama setup
• GitHub Releases — release body options

Development

pnpm install && pnpm build && pnpm test — see CONTRIBUTING.md for the full guide.

Support

• GitHub Issues — bug reports and feature requests
• Contributing — development setup and PR guidelines
• Security policy — reporting vulnerabilities
• Code of Conduct

License

MIT