Repository files navigation

🚀 Generic CLI tool to automate versioning and package publishing-related tasks:

• Bump version (in e.g.package.json)
• Git commit, tag, push
• Execute any (test or build) commands usinghooks
• Create release at GitHub orGitLab
• Generate changelog
• Publish to npm
• Manage pre-releases
• Extend withplugins
• Release from anyCI/CD environment

Use release-it for version management and publish to anywhere with its versatile configuration, a powerful pluginsystem, and hooks to execute any command you need to test, build, and/or publish your project.

Are you using release-it at work? Please considersponsoring me!

Although release-it is ageneric release tool, most projects use it for projects with npm packages. The recommendedway to install release-it uses npm and adds some minimal configuration to get started:

npm init release-it

Alternatively, install it manually, and add therelease script topackage.json:

npm install -D release-it

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

Run release-it from the root of the project using eithernpm run ornpx:

npm run releasenpx release-it

You will be prompted to select the new version, and more prompts will follow based on your configuration.

• Using Yarn? Please see thenpm section on Yarn.
• Using pnpm? Please seerelease-it-pnpm.

Using a monorepo? Please see thismonorepo recipe.

Per-project installation as shown above is recommended, but global installs are supported as well:

• From npm:npm install -g release-it
• From Homebrew:brew install release-it

UseRelease It! - Containerized to run it in any environment as a standardized container without the need for aNode environment. ThanksJuan Carlos!

Here's a list of interesting external resources:

• Video:How to use GitHub Actions & Release-It to Easily Release Your Code
• Article:Monorepo Semantic Releases (repo)

Want to add yours to the list? Just open a pull request!

Out of the box, release-it has sane defaults, andplenty of options to configure it. Most projects use a.release-it.json file in the project root, or arelease-it property inpackage.json.

Here's a quick example.release-it.json:

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

→ SeeConfiguration for more details.

By default, release-it isinteractive and allows you to confirm each task before execution:

By using the--ci option, the process is fully automated without prompts. The configured tasks will be executed asdemonstrated in the first animation above. In a Continuous Integration (CI) environment, this non-interactive mode isactivated automatically.

Use--only-version to use a prompt only to determine the version, and automate the rest.

How does release-it determine the latest version?

1. For projects with apackage.json, itsversion will be used (seenpm to skip this).
2. Otherwise, release-it uses the latest Git tag to determine which version should be released.
3. As a last resort,0.0.0 will be used as the latest version.

Alternatively, a plugin can be used to override this (e.g. to manage aVERSION orcomposer.json file):

• @release-it/bumper to read from or bump the version in any file
• @release-it/conventional-changelog to get a recommended bump based on commit messages
• release-it-calver-plugin to use CalVer (Calendar Versioning)

Add the--release-version flag to print thenext version without releasing anything.

Git projects are supported well by release-it, automating the tasks to stage, commit, tag and push releases to any Gitremote.

→ SeeGit for more details.

As of July 2025, GitHub and GitLab CI workflows can now use npm'sTrusted Publishing OpenID Connect (OIDC)integration for secure, token-free publishing from CI/CD. This eliminates long-lived tokens and automatically generatesprovenance attestations. Seedocs/npm.md for details.

GitHub projects can have releases attached to Git tags, containing release notes and assets. There are two ways to addGitHub releases in your release-it flow:

1. Automated (requires aGITHUB_TOKEN)
2. Manual (using the GitHub web interface with pre-populated fields)

→ SeeGitHub Releases for more details.

GitLab projects can have releases attached to Git tags, containing release notes and assets. To automateGitLabreleases:

• Configuregitlab.release: true
• Obtain apersonal access token (release-it needs theapi andself_rotate scopes).
• Make sure the token isavailable as an environment variable.

→ SeeGitLab Releases for more details.

By default, release-it generates a changelog, to show and help select a version for the new release. Additionally, thischangelog serves as the release notes for the GitHub or GitLab release.

Thedefault command is based ongit log .... This setting (git.changelog) can be overridden. To furthercustomize the release notes for the GitHub or GitLab release, there'sgithub.releaseNotes orgitlab.releaseNotes.Make sure any of these commands output the changelog tostdout. Note that release-it by default is agnostic to commitmessage conventions. Plugins are available for:

• GitHub and GitLab Releases
• auto-changelog
• Conventional Changelog
• Keep A Changelog
• git-cliff

To print the changelog without releasing anything, add the--changelog flag.

→ SeeChangelog for more details.

With apackage.json in the current directory, release-it will letnpm bump the version inpackage.json (andpackage-lock.json if present), and publish to the npm registry.

→ SeePublish to npm for more details.

With release-it, it's easy to create pre-releases: a version of your software that you want to make available, whileit's not in the stable semver range yet. Often "alpha", "beta", and "rc" (release candidate) are used as identifiers forpre-releases. An example pre-release version is2.0.0-beta.0.

→ SeeManage pre-releases for more details.

Use--no-increment to not increment the last version, but update the last existing tag/version.

This may be helpful in cases where the version was already incremented. Here are a few example scenarios:

• To update or publish a (draft) GitHub Release for an existing Git tag.
• Publishing to npm succeeded, but pushing the Git tag to the remote failed. Then userelease-it --no-increment --no-npm to skip thenpm publish and try pushing the same Git tag again.

Use script hooks to run shell commands at any moment during the release process (such asbefore:init orafter:release).

The format is[prefix]:[hook] or[prefix]:[plugin]:[hook]:

Use the optional:plugin part in the middle to hook into a life cycle method exactly before or after any plugin.

The core plugins includeversion,git,npm,github,gitlab.

Note that hooks likeafter:git:release will not run when either thegit push failed, or when it is configured not tobe executed (e.g.git.push: false). Seeexecution order for more details on execution order of plugin lifecyclemethods.

All commands can use configuration variables (like template strings). An array of commands can also be provided, theywill run one after another. Some example release-it configuration:

{"hooks": {"before:init": ["npm run lint","npm test"],"after:my-plugin:bump":"./bin/my-script.sh","after:bump":"npm run build","after:git:release":"echo After git push, before github release","after:release":"echo Successfully released ${name} v${version} to ${repo.repository}."  }}

The variables can be found in thedefault configuration. Additionally, the following variables are exposed:

versionlatestVersionchangelognamerepo.remote, repo.protocol, repo.host, repo.owner, repo.repository, repo.projectbranchNamereleaseUrl

All variables are available in all hooks. The only exception is that the additional variables listed above are not yetavailable in theinit hook.

Use--verbose to log the output of the commands.

For the sake of verbosity, the full list of hooks is actually:init,beforeBump,bump,beforeRelease,releaseorafterRelease. However, hooks likebefore:beforeRelease look weird and are usually not useful in practice.

Note that arguments need to be quoted properly when used from the command line:

release-it --'hooks.after:release="echo Successfully released ${name} v${version} to ${repo.repository}."'

Using Inquirer.js inside custom hook scripts might cause issues (since release-it also uses this itself).

Use--dry-run to show the interactivity and the commands itwould execute.

→ SeeDry Runs for more details.

• Withrelease-it --verbose (or-V), release-it prints the output of every user-definedhook.
• Withrelease-it -VV, release-it also prints the output of every internal command.
• UseNODE_DEBUG=release-it:* release-it [...] to print configuration and more error details.

Useverbose: 2 in a configuration file to have the equivalent of-VV on the command line.

Since v11, release-it can be extended in many, many ways. Here are some plugins:

Internally, release-it uses its own plugin architecture (for Git, GitHub, GitLab, npm).

→ See allrelease-it plugins on npm.

→ Seeplugins for documentation to write plugins.

While mostly used as a CLI tool, release-it can be used as a dependency to integrate in your own scripts. Seeuserelease-it programmatically for example code.

• AdonisJs
• Axios
• Chakra UI
• Halo
• hosts
• js-cookie
• jQuery
• Madge
• Metalsmith
• n8n
• Node-Redis
• React Native Paper
• Readability.js
• Redux
• Saleor
• Semantic UI React
• tabler-icons
• Swagger (swagger-ui +swagger-editor)
• Repositories that depend on release-it
• GitHub search forpath:**/.release-it.json

The latest major version is v19, supporting Node.js 20 and up:

Also seeCHANGELOG.md for dates and details.

• SeeCHANGELOG.md for major/breaking updates, andreleases for a detailed version history.
• Tocontribute, please readCONTRIBUTING.md first.
• Pleaseopen an issue if anything is missing or unclear in this documentation.

MIT

Are you using release-it at work? Please considersponsoring me!