release-it leaves three decisions to you: the bump, the changelog and the credential

`npm init release-it` writes the config you would otherwise hand copy

The recommended install is one command that also sets up a starting configuration:

npm init release-it

The manual route is a dev dependency plus a script entry, because release-it has to be on the path of the project's own release command:

npm install -D release-it

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

Per project installation is the recommended shape, and global installs exist anyway: `npm install -g release-it` or `brew install release-it`. The cost of a global install is that nothing pins it, so two machines running the same repository can automate the same release with different tool versions. For environments with no Node at all, the documentation points to a separate containerized image instead of asking you to install anything locally.

Version discovery falls back to `0.0.0` and keeps going

Before it can bump anything, release-it has to decide what the current version is, and the lookup is a three step ladder. For a project with a `package.json`, that file's `version` is used. Otherwise the latest Git tag becomes the version. If neither exists, `0.0.0` is used as the latest version.

That last rung is the one to think about. A repository with no manifest and no tags does not get an error; it gets `0.0.0` treated as fact, and the prompt that follows offers bumps computed from that floor.

Two flags let you inspect this without acting. `--release-version` prints the next version and releases nothing; when no next version is available it prints nothing and exits successfully, which makes an empty result ambiguous in a script. And a plugin can replace the whole ladder: `@release-it/bumper` reads from or bumps a version in any file, `@release-it/conventional-changelog` derives the bump from commit messages, and `release-it-calver-plugin` switches to calendar versioning.

`--ci` removes the prompts, and CI turns it on without being asked

Out of the box the tool is interactive and asks you to confirm each task before it runs. `--ci` runs the whole configured sequence with no prompts at all, and in a Continuous Integration environment that non interactive mode is activated automatically, so the same command behaves differently depending on where it runs.

That automatic switch is the useful part and the trap. A release rehearsed on a laptop goes through prompts you answer by reading; the identical command in CI skips them, so a misconfigured task that you would have caught locally becomes an unattended commit, tag, push and publish. The middle option is `--only-version`: prompt once for the version, then automate everything after it. That keeps a human on the decision that matters and leaves the mechanics to the tool.

Hooks are the other half of this design. Any test or build command can be executed as a hook, which is where release-it expects your verification to live. It does not run your suite on its own; if the hook is not configured, the release proceeds without it, and the confirmation you skipped in CI is the only thing that would have caught it.

Three credential arrangements, one per forge, plus OIDC for npm

Release notes attached to Git tags come in two shapes. The automated path for GitHub requires a `GITHUB_TOKEN`. The manual path uses the GitHub web interface with pre-populated fields, which means copying the generated notes by hand.

GitLab takes three explicit steps: set `gitlab.release: true`, obtain a personal access token that carries the `api` and `self_rotate` scopes, and make sure that token is available as an environment variable.

For npm itself the story has changed. As of July 2025, GitHub and GitLab CI workflows can use npm's Trusted Publishing OpenID Connect integration, which removes long lived tokens and automatically generates provenance attestations. The trade is that this path only works inside those CI systems and only for npm; the GitHub and GitLab release steps above still need their own tokens. A project on another CI system keeps the old arrangement, with the credential its registry accepts stored as a secret.

The changelog is a `git log` command that has to reach stdout

A changelog is generated by default, and it does double duty: it is what you read when picking a version and it becomes the release notes on GitHub or GitLab. The default command is based on `git log`, and `git.changelog` can override it. For the release body specifically there are `github.releaseNotes` and `gitlab.releaseNotes`.

One constraint shapes all of it: the command must print the changelog to `stdout`. A custom script that writes a file, or logs through a progress reporter on another stream, produces release notes that are empty or truncated, and the same broken text can end up as the published notes. `--changelog` prints the changelog without releasing anything, which is the cheap way to see what a command actually emits.

The second constraint is about meaning. By default release-it is agnostic to commit message conventions, so a history full of `fix:` and `feat:` prefixes is read as ordinary text and does not move the version. Plugins change that: Conventional Changelog, auto-changelog, Keep A Changelog, git-cliff, and the ones covering GitHub and GitLab releases. Until one is added, the bump comes from what a person types at the prompt.

Version 21 is an ESM package that ships its schema and releases itself

The published package is `release-it` at version 21.1.2, MIT licensed, authored by Lars Kappert. Its shape is worth knowing before you script around it. `"type": "module"` marks the whole package as ESM, the single binary maps `release-it` to `bin/release-it.js`, and the exports map sends both `import` and `require` of the root entry to the same `./lib/index.js`, with types from `./types/index.d.ts`. Two extra export paths are published as well, `./package.json` and `./test/util/index.js`.

The `files` array ships `bin`, `config`, `lib`, `test`, `schema` and `types`, so the JSON schema for configuration and the test utilities travel with the package rather than staying in the repository.

The project releases itself with its own tool: the `release` script is `./bin/release-it.js`. Development runs on pnpm, given `pnpm-lock.yaml` and `pnpm-workspace.yaml`, with `lint` as `eslint lib test`, `format` through prettier, `docs` through remark over README and docs markdown, and `knip` as a separate unused dependency check configured by `knip.json`. The test script is `node --env-file=.env.test --test && installed-check --no-workspaces`, using the Node test runner with an environment file at the repository root.

Monorepos, pnpm and bump inference are all deferred elsewhere

Three common situations are answered by pointing at other projects rather than by documenting a built in path. Yarn users are sent to the npm section on Yarn, pnpm users to a separate `release-it-pnpm` package, and monorepo users to a monorepo recipe. That is a reasonable division of labor, but it means the behavior you get in those setups comes from somewhere else, and version drift between this tool and that recipe is your problem to track.

Pre-releases work the way the documentation describes them: a version outside the stable semver range, with `alpha`, `beta` and `rc` used as identifiers and `2.0.0-beta.0` given as the example. `--no-increment` exists for updating or re-running an existing release without moving the last version, and publish to npm will let `npm` bump `package.json` and `package-lock.json` when both are present. The npm path is the one step that hands version writing to another tool, which is worth knowing before you point it at a registry.

Editorial conclusion

release-it earns its place in a repository that already has one package.json, a tag convention and a working publish credential, because it turns a ten command ritual into a confirmed checklist. Skip it if the bump should come from commit messages, because that needs the conventional-changelog or bumper plugin, and for a monorepo or pnpm follow the monorepo recipe or release-it-pnpm that the documentation points to. Two checks before the first run: confirm what the changelog command writes to, since it has to reach stdout, and confirm which token your CI actually has, because a GITHUB_TOKEN, a GitLab personal access token with the api and self_rotate scopes, and npm Trusted Publishing are three different arrangements.

Frequently asked questions

Official sources

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