release-it

Files (23)

• SKILL.md
• README.md · evals/
• comparison-results.md · evals/
• evals.json · evals/
• forward-results.json · evals/
• interactive-results.json · evals/
• plugin-results.json · evals/
• run_interactive.py · evals/
• run_plugin_contracts.mjs · evals/
• release-prompts.mjs · examples/interactive-release/
• release.mjs · examples/interactive-release/
• cli-and-workflow.md · references/
• configuration.md · references/
• custom-plugin-development.md · references/
• git-integration.md · references/
• github-gitlab-releases.md · references/
• hooks-and-lifecycle.md · references/
• initial-setup.md · references/
• interactive-workflow.md · references/
• monorepo.md · references/
• npm-publishing.md · references/
• plugins.md · references/
• troubleshooting.md · references/

SKILL.md (first lines)

# release-it Release Automation

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](references/configuration.md) and
  [cli-and-workflow.md](references/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](references/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](references/plugins.md) and
  [custom-plugin-development.md](references/custom-plugin-development.md). Tooling manifests do
  not determine the application's version source.
- **Dirty state, cancellation, or recovery:** use [git-integration.md](references/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](references/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

```bash
# After generating the entry script, adapter, and target config:
pnpm release
```

For first-time setup with project-aware configuration, follow [initial-setup.md](references/initial-setup.md).

## Capability Index

Read the reference file that matches your task:

| Reference | When to Read |
|-----------|-------------|
| [initial-setup.md](references/initial-setup.md) | First-time setup. Analyze project → propose config → ask user for decisions → generate tailored config |
| [interactive-workflow.md](references/interactive-workflow.md) | Default Inquirer flow, executable entry/adapter examples, explicit version selection, cancellation and compatibility |
| [monorepo.md](references/monorepo.md) | Select one service app and bind its cwd, version, changelog, and tags |
| [configuration.md](references/configuration.md) | Setting up or modifying `.release-it.*` config in any format, config extends/merging, CLI overrides |
| [hooks-and-lifecycle.md](references/hooks-and-lifecycle.md) | Adding pre/post release commands, understanding execution order, template variables |
| [cli-and-workflow.md](references/cli-and-workflow.md) | CLI flags, increment types, pre-release flow, dry-run, CI mode, programmatic API |
| [git-integration.md](references/git-integration.md) | Working state, staging and recovery scope, tag naming/matching, branch restrictions, push config |
| [npm-publishing.md](references/npm-publishing.md) | npm auth, scoped packages, dist-tags, OTP/2FA, OIDC Trusted Publishing, monorepo, private registry |
| [github-gitlab-releases.md](references/github-gitlab-releases.md) | GitHub/GitLab release creation, tokens, assets, release notes, comments, draft/pre-release |
| [plugins.md](references/plugins.md) | Setting up official/community plugins (conventional-changelog, bumper, keep-a-changelog, etc.) |
| [custom-plugin-development.md](references/custom-plugin-development.md) | Building a custom release-it plugin from scratch, Plugin class API reference |
| [troubleshooting.md](references/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](references/configuration.md) for all defaults and the `extends` mechanism.

## Common Workflows

**Initial setup**: [initial-setup.md](references/initial-setup.md) — analyzes project, proposes config, asks for decisions

**Add changelog generation**: [plugins.md](references/plugins.md) → conventional-changelog or keep-a-changelog section

**CI/CD pipeline (GitHub Actions)**: [cli-and-workflow.md](references/cli-and-workflow.md) → CI mode + [npm-publishing.md](references/npm-publishing.md) → authentication

**Pre-release (alpha/beta/rc)**: [cli-and-workflow.md](references/cli-and-workflow.md) → pre-release workflow

**Custom release steps**: [hooks-and-lifecycle.md](references/hooks-and-lifecycle.md) → hook configuration

From buYoung/skills, MIT.

More from buYoung/skills