cloudparts

release-it

A Node.js command that runs a whole release in one go: pick the next version, bump it, commit, tag, push, create a GitHub or GitLab release and publish to npm, asking before each step unless it runs in CI.

What it is
Release automation
Type
Open source
Made by
Lars Kappert and contributors
License
MIT
Facts checked
13 October 2026
Website Source code

What it is

Run npx release-it and it works out the current version (from package.json, else the latest Git tag, else 0.0.0), shows the changelog since the last tag, and asks which version comes next. Then it runs its steps in order: npm version to bump package.json and the lockfile, git commit, an annotated git tag, git push --follow-tags, a GitHub or GitLab release with the changelog as its notes, and npm publish. Interactively it asks for confirmation before each step; with --ci, or when it detects a CI environment, it runs them all without prompts, and --dry-run prints the commands it would run.

Before starting it checks the repository: by default the working directory must be clean and the branch must have an upstream, and git.requireBranch can restrict releases to one branch. Configuration lives in .release-it.json or a release-it key in package.json. Hooks run your own commands at fixed points, named before: or after: plus a step (init, bump, release) and optionally a plugin (git, npm, github, gitlab), so before:init can run the tests and after:bump can build with the new version number.

Out of the box release-it ignores commit message conventions: its changelog is a git log of subjects since the last tag, and you choose the version. Plugins change that. @release-it/conventional-changelog recommends a bump from Conventional Commits and writes CHANGELOG.md, @release-it/bumper reads and writes the version in any file, and others add Keep a Changelog, git-cliff, calendar versioning, .NET or pnpm workspaces. Git, npm, GitHub and GitLab are themselves built-in plugins, and any of them can be switched off with flags like --no-npm.

Why teams pick it

  • One command covers the routine of a release, and the interactive mode lets you confirm or skip each step the first few times
  • Works for any Git project, not only npm packages: turn off the npm plugin and it still bumps, tags, pushes and creates the GitHub or GitLab release
  • Hooks and plugins at every step make it easy to run tests, builds or extra publishing without wrapper scripts
  • Supports npm trusted publishing (OIDC) from GitHub and GitLab CI, and staged publishing that defers the 2FA approval to a maintainer

Watch out for

  • Built around one package per repository: monorepos need the documented monorepo recipe or a workspaces plugin
  • Version 21 (July 2026) requires Node.js 22 or newer and parses CLI flags strictly, so older Node and loose flags break on upgrade
  • If a step fails partway, for example the npm publish succeeds but the tag push fails, you finish by hand with --no-increment and flags that skip the steps already done
  • The default changelog is just commit subjects; readable release notes need conventional commits and a plugin, or a hand-written CHANGELOG

Alternatives

What all release automation have in common →Compare side by side →
cargo-semver-checksOpen sourceA Cargo subcommand that compares a Rust crate’s public API with its last published version and fails if the change needs a bigger version bump than the one you chose, such as removing a public item in a patch release.release-plzOpen sourceA release tool for Rust that runs in CI: it keeps a release pull request with the next versions and changelogs of your crates up to date, and when you merge it, publishes the new versions to crates.io, tags them and creates GitHub, GitLab or Gitea releases.

How it fits with other technologies

.release-it.json: test first, build after the bump, release on GitHub · json

{
  "$schema": "https://unpkg.com/release-it@21/schema/release-it.json",
  "git": {
    "commitMessage": "chore: release v${version}",
    "requireBranch": "main"
  },
  "github": { "release": true },
  "hooks": {
    "before:init": ["npm run lint", "npm test"],
    "after:bump": "npm run build",
    "after:release": "echo Released ${name} v${version}"
  }
}

See it in a real stack

No architecture uses release-it yet. Drop it into the playground and wire it up yourself.Open playground →
Where it came from2014–2026

Releasing a JavaScript package by hand is a fixed sequence that is easy to get wrong: edit the version, commit, tag, push the tag, publish to npm, write the release notes, and do it again next time in the same order. Lars Kappert published release-it to npm in January 2014 as an “interactive release tool for Git repositories”, which could also build and push to a separate distribution repository and publish to npm.

By 1.0.0 in August 2015 the pitch was “bump version, commit, tag, push, publish, done”, with a dry-run mode, a non-interactive mode and GitHub releases; the README noted that release-it had released itself. Later majors kept that core and reshaped everything around it. Versions 9 and 10 dropped the distribution-repository feature. Version 11 (May 2019) introduced plugins, handed the package.json bump to npm version so lockfiles stay in sync, and rolled back the release commit and tag when a release was cancelled or failed. Version 13 (2020) replaced the old scripts with hooks and --non-interactive with --ci.

Version 15 (April 2022) moved to ES modules and removed anonymous usage metrics. Since then most majors have dropped old Node.js versions; version 21 (July 2026) requires Node.js 22, makes CLI parsing strict and verifies GitLab certificates by default. The latest release is 21.1.1, from October 7, 2026.

Why it’s built this way

Interactive by default, with a CI mode
A release is hard to undo, so release-it asks before each commit, tag, push and publish when a person runs it, and only skips the prompts with --ci or in a detected CI environment.
Stay neutral about commit conventions
The core changelog is plain git log output and the version is chosen at the prompt; conventional commits, Keep a Changelog or calendar versioning come in as plugins, so the tool fits projects whatever their commit style.
Let npm bump the version (v11)
Delegating to npm version updates package-lock.json and npm-shrinkwrap.json together with package.json, instead of release-it editing files itself.
Build the core on its own plugin system (v11)
Git, npm, GitHub and GitLab became plugins with lifecycle methods, so third-party plugins can hook into the same steps and any built-in one can be turned off.

Timeline

  1. 2014

    First published to npm by Lars Kappert (January 15)

  2. 2015

    1.0.0 (August 20): bump, commit, tag, push, publish, with dry runs and GitHub releases

  3. 2019

    11.0.0 (May 1): plugins, npm version bumps, rollback on failure

  4. 2020

    13.0.0 (March 7): hooks replace scripts; --ci replaces --non-interactive

  5. 2022

    15.0.0 (April 30): ES modules only, anonymous metrics removed

  6. 2026

    21.0.0 (July 25): Node.js 22 required, strict CLI parsing; 21.1.1 released October 7

Sources8 · facts checked 13 October 2026

Improve this page on GitHub