release-it is a generic, pluggable CLI tool that automates versioning and package publishing. It handles version bumping, Git committing/tagging/pushing, npm publishing, and GitHub/GitLab release creation -- all in a single configurable workflow. Language-agnostic with a powerful plugin system for extending behavior.
Choose the Applying Workflow
Start with the requested operation and the project's existing release entry point. A config repair, CI job, publishing workflow, or plugin does not by itself require a new interactive wrapper. Preserve the chosen execution mode and enabled capabilities when fixing it.
- Configuration, CLI, or CI: use configuration.md and cli-and-workflow.md; load publishing references when applicable.
- Programmatic wrapper: inspect the API, prompt/log ownership, and installed version using cli-and-workflow.md. Use the interactive contract below when generating the service-app command, not as an override for every API caller.
- Version source or custom plugin: use plugins.md and custom-plugin-development.md. Tooling manifests do not determine the application's version source.
- Dirty state, cancellation, or recovery: use git-integration.md to distinguish write paths, staging scope, the shared index, and recoverable state.
The concrete adapter and source-level behavior in this skill are checked against release-it 21.0.1. Match configuration schemas, runtime requirements, and plugin interfaces to the applying project's version; an example's dependency pin is not an instruction to upgrade it.
Default Interactive Contract
For a new interactive service-app release command, generate pnpm release using the project entry script and @inquirer/prompts adapter in
interactive-workflow.md. All release questions use
Inquirer; release-it performs the version update and Git operations.
- Single project:
pnpm release → choose version → confirm commit / commit → confirm tag / tag → confirm push / push. - Monorepo:
pnpm release → choose one service app → choose version → confirm commit / commit → confirm tag / tag → confirm push / push.
The first question in a non-monorepo is the version selection. Do not add an app picker or a separate start confirmation. In a monorepo, offer only the verified service apps with a single-select picker, even when there is only one eligible app. Resolve an unclear service app boundary during setup, then use that app's version source, changelog, and tag policy.
Display the current version and concrete next versions. Always wait for the user's selection; recommended increments, existing settings, and CI environment variables cannot replace it. Pass the selected exact version and target configuration to release-it's API.
Ask each Git confirmation at its release-it execution point and await that action before
asking the next. A negative answer or cancellation stops that action and the entire remaining
flow. Use Inquirer's native y/n confirmation with default: true for commit, tag, and push,
so Enter approves the displayed action, including push;
Ctrl+C cancels the active question. Report the actual remaining files, index, commit, tag,
and push status according to the chosen recovery policy. The packaged example preserves
interrupted work; automatic restoration needs explicit scope and baseline handling.
Check for an interactive terminal before any release work. Do not use
--ci, --only-version, canned answers, or a direct push hook in this default path.
CI automation, npm publishing, and hosted releases remain supported as explicitly requested extensions with their own configuration. Do not infer them from a Git remote or add them to the default service-app flow. Read the adapter compatibility notes before applying it to a different release-it version; its injection surface is confirmed in source, not a stable CLI option.
Quick Start
# After generating the entry script, adapter, and target config:
pnpm release
For first-time setup with project-aware configuration, follow initial-setup.md.
Capability Index
Read the reference file that matches your task:
| Reference | When to Read |
|---|---|
| initial-setup.md | First-time setup. Analyze project → propose config → ask user for decisions → generate tailored config |
| interactive-workflow.md | Default Inquirer flow, executable entry/adapter examples, explicit version selection, cancellation and compatibility |
| monorepo.md | Select one service app and bind its cwd, version, changelog, and tags |
| configuration.md | Setting up or modifying .release-it.* config in any format, config extends/merging, CLI overrides |
| hooks-and-lifecycle.md | Adding pre/post release commands, understanding execution order, template variables |
| cli-and-workflow.md | CLI flags, increment types, pre-release flow, dry-run, CI mode, programmatic API |
| git-integration.md | Working state, staging and recovery scope, tag naming/matching, branch restrictions, push config |
| npm-publishing.md | npm auth, scoped packages, dist-tags, OTP/2FA, OIDC Trusted Publishing, monorepo, private registry |
| github-gitlab-releases.md | GitHub/GitLab release creation, tokens, assets, release notes, comments, draft/pre-release |
| plugins.md | Setting up official/community plugins (conventional-changelog, bumper, keep-a-changelog, etc.) |
| custom-plugin-development.md | Building a custom release-it plugin from scratch, Plugin class API reference |
| troubleshooting.md | Debugging release failures, auth errors, CI issues, common error messages |
Config Formats Overview
release-it supports 6 config file formats. Pick one:
| Format | File | Notes |
|---|---|---|
| JSON | .release-it.json |
Most common. Supports $schema for IDE autocomplete |
| TypeScript | .release-it.ts |
Type hints via satisfies Config |
| JS/CJS | .release-it.js / .release-it.cjs |
Dynamic config, functions for releaseNotes |
| YAML | .release-it.yaml / .release-it.yml |
Compact syntax |
| TOML | .release-it.toml |
Table-based config |
| package.json | "release-it": {} property |
Zero extra files |
Example schema for the checked version: "$schema": "https://unpkg.com/release-it@21.0.1/schema/release-it.json".
Use the applying project's release-it version when generating its configuration.
Only override options that differ from defaults. See configuration.md for all defaults and the extends mechanism.
Common Workflows
Initial setup: initial-setup.md — analyzes project, proposes config, asks for decisions
Add changelog generation: plugins.md → conventional-changelog or keep-a-changelog section
CI/CD pipeline (GitHub Actions): cli-and-workflow.md → CI mode + npm-publishing.md → authentication
Pre-release (alpha/beta/rc): cli-and-workflow.md → pre-release workflow
Custom release steps: hooks-and-lifecycle.md → hook configuration
Monorepo service app: monorepo.md + interactive-workflow.md
Explicit multi-package publishing: npm-publishing.md → monorepo section + plugins.md → workspaces/bumper
Something broke: troubleshooting.md
Build a plugin: custom-plugin-development.md
Key Concepts
- Increment types (UX order, most-used first):
patch→minor→prepatch(alpha) →preminor(beta) →prerelease(rc counter) →major→premajor. semver bumps plus pre-release variants, ordered by typical usage frequency - Dry-run (
--dry-run): Skips writes routed through release-it's shell layer.$= read-only (runs),!= write (skipped). Plugins must guard direct filesystem/network effects themselves - CI mode (
--ci): Non-interactive, auto-detected in CI environments. No prompts, uses spinners instead - npm dist-tags:
latest(default),next,beta,alpha-- controls whatnpm installresolves to - Plugin lifecycle:
init→getName→getLatestVersion→beforeBump→bump→beforeRelease→release→afterRelease - Hooks: Shell commands run at lifecycle points (
before:init,after:bump,after:release, etc.) - Template variables:
${version},${latestVersion},${tagName},${changelog},${name}-- available in config strings - Config precedence: CLI args > config file >
extendsbase > built-in defaults