release-it: a CLI for version bumps, Git tags and npm publishing

What release-it replaces in a manual release

A release usually means editing a version field, committing that edit, tagging the commit, pushing, writing release notes, and publishing an artefact. release-it groups those steps behind one command. The README describes it as a "generic CLI tool to automate versioning and package publishing-related tasks" and lists the individual jobs: bumping the version in package.json, committing, tagging and pushing in Git, running test or build commands through hooks, creating GitHub or GitLab releases, generating a changelog, publishing to npm, and managing pre-releases.

The intended audience is a team that ships from Git and wants the release steps to be repeatable rather than typed by hand. The generic label matters: the README notes that most projects use it for npm packages, but the tool is not limited to that. Hooks let a release run any command, so a project can build or publish through something other than npm.

How release-it decides the version and drives the release

The version source is a fallback chain, and the README states it plainly. For a project with a package.json, its version field is used. Otherwise release-it falls back to the latest Git tag. If neither exists, 0.0.0 is used as the latest version. A plugin can override this: the README names @release-it/bumper for reading or bumping a version in any file, @release-it/conventional-changelog for a recommended bump based on commit messages, and release-it-calver-plugin for CalVer.

The changelog is generated by default and is based on a git log command. That setting is git.changelog, and the README says it can be overridden; the command must write to stdout. release-it is agnostic to commit message conventions by default, and plugins exist for auto-changelog, Conventional Changelog, Keep A Changelog and git-cliff. The same changelog becomes the release notes for a GitHub or GitLab release, and github.releaseNotes or gitlab.releaseNotes can replace it.

GitHub releases can be automated with a GITHUB_TOKEN or created manually through the web interface with pre-populated fields. For GitLab, the README says to set gitlab.release to true, obtain a personal access token with the api and self_rotate scopes, and make the token available as an environment variable. The README also notes that as of July 2025 GitHub and GitLab CI workflows can use npm Trusted Publishing with OpenID Connect for token-free publishing, which removes long-lived tokens and generates provenance attestations.

Installing release-it and running a first release

The README recommends the npm route with minimal configuration. This command scaffolds release-it into the project and adds the starting configuration:

npm init release-it

If you prefer to install it manually, add it as a dev dependency and define a release script. The README gives this package.json shape:

{
  "name": "my-package",
  "version": "1.0.0",
  "scripts": {
    "release": "release-it"
  },
  "devDependencies": {
    "release-it": "^21.0.0"
  }
}

Configuration usually lives in a .release-it.json file at the project root or in a release-it property in package.json. The README's quick example sets a commit message template and turns on GitHub releases:

{
  "$schema": "https://unpkg.com/release-it@20/schema/release-it.json",
  "git": {
    "commitMessage": "chore: release v${version}"
  },
  "github": {
    "release": true
  }
}

Run the release from the project root with either of the two documented invocations:

npm run release
npx release-it

In the default interactive mode you are prompted to select the new version, and further prompts follow based on your configuration. To see what release-it would do without releasing anything, the README documents --release-version, which prints the next version, and --changelog, which prints the changelog.

Interactive mode, CI mode and the --only-version path

release-it is interactive by default: the README says it allows you to confirm each task before execution. The --ci option removes prompts and runs the configured tasks automatically. In a CI environment this non-interactive mode is activated automatically, so a pipeline does not need to pass --ci explicitly. A third option, --only-version, prompts only for the version and automates the rest. That middle path is the one to consider if you want a human to pick the number but do not want to answer questions about tags and publishing.

The trade-off is that automation depends on the configuration being complete and correct before the run starts. Interactive mode lets you catch a wrong version or a missing token at the prompt; CI mode does not. The README does not document a dry-run flag that executes the full release without side effects, so the safe checks are the read-only flags: --release-version and --changelog.

Where release-it is the wrong tool

The version fallback chain is the first constraint. If your project keeps its version somewhere release-it cannot see, the tool will use the latest Git tag or 0.0.0 instead. The README points to @release-it/bumper for reading or bumping a version in any file, which means an extra plugin is required rather than a configuration key.

The second constraint is that release-it is a JavaScript tool. The README lists a containerized option, Release It! - Containerized, for running it in any environment without a Node environment, and it documents a global install through npm or Homebrew. Those are the documented paths around the Node requirement; there is no documented non-JavaScript implementation.

The third is scope. release-it orchestrates steps; it does not decide whether a release is warranted. Without @release-it/conventional-changelog, the README states that release-it is agnostic to commit message conventions, so the recommended bump has to come from somewhere else. If your team expects the tool to infer the next version from commit history out of the box, that expectation does not match the default behaviour.

release-it against semantic-release

semantic-release is the closest alternative in this space, and the difference is where the version decision happens. semantic-release derives the release from commit messages according to a convention, so the version is computed rather than chosen. release-it starts from an explicit version source (package.json, the latest Git tag, or 0.0.0) and, in its default mode, asks a human to select the new version. The README's plugin list is the bridge between the two approaches: @release-it/conventional-changelog computes a recommended bump from commit messages, which moves release-it toward the semantic-release model without requiring it.

The practical consequence is the failure mode. With semantic-release, a commit message that does not match the convention can produce an unexpected or missing release. With release-it, a wrong version selected at the prompt is committed and tagged as-is. Which risk you prefer depends on whether you trust the prompt or the convention more.

Licence, maintenance and upgrade cost

release-it is MIT-licensed, and the package.json lists Lars Kappert as the author, with funding links to GitHub Sponsors and Open Collective. The repository is not archived, and the last push was on 2026-09-17, the same day as the 21.1.0 release; 21.0.3 shipped on 2026-09-14 and 21.0.2 on 2026-08-09. Those dates come from the repository metadata, not from a release cadence guarantee.

The upgrade cost is mostly configuration drift and plugin compatibility. The README's example .release-it.json points its $schema at release-it@20 while the current package version is 21.1.0, so schema references in existing configs are worth checking against the version you install. Plugins such as @release-it/bumper, @release-it/conventional-changelog and release-it-calver-plugin are separate packages, and their compatibility with a given release-it major version is not stated in the README. GitLab automation also depends on a personal access token with the api and self_rotate scopes, so token rotation is part of the maintenance surface. Nothing here is legal advice; the MIT licence text in the repository is the authoritative source.

Editorial conclusion

release-it is a good fit for npm-based projects that already release from Git and want the bump, tag, changelog and publish steps in one command. It is the wrong tool if you need a release process that cannot be expressed as a shell command or a plugin hook, or if you want a tool that manages version files outside its documented fallback chain. Before adopting it, check that the version source it will use (package.json, the latest Git tag, or 0.0.0) matches where your project keeps its version, and confirm the token scopes your GitLab or GitHub automation needs.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. release-it/release-it on GitHub
5. Releases