semantic-release
AboutGitHubNeed Help?
next
next
  • Introduction
  • Usage
    • Getting started
    • Installation
    • CI Configuration
    • Configuration
    • Plugins
    • Workflow configuration
    • Shareable configurations
  • Extending
    • Plugins
    • Shareable configuration
  • Recipes
    • CI configurations
      • CircleCI 2.0
      • Travis CI
      • GitLab CI
    • Git hosted services
      • Git authentication with SSH keys
    • Package managers and languages
  • Developer guide
    • JavaScript API
    • Plugin development
    • Shareable configuration development
  • Support
    • Resources
    • Frequently Asked Questions
    • Troubleshooting
    • Node version requirement
    • Node Support Policy
Powered by GitBook
On this page
  • Why is the package.json’s version not updated in my repository?
  • How can I use a npm build script that requires the package.json’s version ?
  • Is there a way to preview which version would currently get published?
  • Can I use semantic-release with Yarn?
  • Can I use semantic-release to publish non-JavaScript packages?
  • Can I use semantic-release with any CI service?
  • Can I run semantic-release on my local machine rather than on a CI server?
  • Can I use semantic-release with GitLab?
  • Can I use semantic-release with any Git hosted environment?
  • Can I skip the release to the npm registry?
  • How can I revert a release?
  • Can I use .npmrc options?
  • How can I set the access level of the published npm package?
  • Can I use semantic-release to publish a package on Artifactory?
  • Can I manually trigger the release of a specific version?
  • Can I exclude commits from the analysis?
  • How can I change the type of commits that trigger a release?
  • Is it really a good idea to release on every push?
  • Can I set the initial release version of my package to 0.0.1?
  • Can I trust semantic-release with my releases?
  • Why does semantic-release require Node version >= 10.18?
  • Why does semantic-release require Git version >= 2.7.1?
  • What is npx?
Edit on Git
  1. Support

Frequently Asked Questions

PreviousResourcesNextTroubleshooting

Last updated 5 years ago

Why is the package.json’s version not updated in my repository?

semantic-release takes care of updating the package.json’s version before publishing to .

By default, only the published package will contain the version, which is the only place where it is really required, but the updated package.json will not be pushed to the Git repository

However, the plugin can be used to push the updated package.json as well as other files to the Git repository.

How can I use a npm build script that requires the package.json’s version ?

The package.json’s version will be updated by the semantic-release command just before publishing to , therefore it won't be available for scripts ran before the semantic-release command.

As the plugin uses the to update the package.json version and publish the package, all will be executed.

You can run your build script in:

  • the prepublishOnly or prepack hook so it will be executed during the publish step of @semantic-release/npm

  • the postversion hook so it will be executed during the prepare step of @semantic-release/npm, which allow for example to update files before committing them with the plugin

If using npm hook scripts is not possible, and alternative solution is to plugin to run your script in the prepare step:

{
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/npm",
    ["@semantic-release/exec", {
      "prepareCmd": "./my-build-script.sh ${nextRelease.version}",
    }],
  ]
}

Is there a way to preview which version would currently get published?

Can I use semantic-release with Yarn?

$ yarn install --ignore-engines

Note: Several CI services use Yarn by default if your repository contains a yarn.lock file. So you should override the install step to specify yarn install --ignore-engines.

$ nvm install 8 && yarn global add semantic-release && semantic-release

Can I use semantic-release to publish non-JavaScript packages?

Yes, semantic-release is a Node CLI application but it can be used to publish any type of packages.

To publish a non-Node package (without a package.json) you would need to:

{
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/github",
    ["@semantic-release/exec", {
      "prepareCmd" : "set-version ${nextRelease.version}",
      "publishCmd" : "publish-package"
      }]
  ]
}

Note: This is a theoretical example where the command set-version update the project version with the value passed as its first argument and publish-package publishes the package to a registry.

Can I use semantic-release with any CI service?

Yes, semantic-release can be used with any CI service, as long as it provides:

Can I run semantic-release on my local machine rather than on a CI server?

$ NPM_TOKEN=<your_npm_token> GH_TOKEN=<your_github_token> npx semantic-release --no-ci

However this is not the recommended approach, as running unit and integration tests on an independent machine before publishing software is a crucial part of the release workflow.

Can I use semantic-release with GitLab?

Can I use semantic-release with any Git hosted environment?

Can I skip the release to the npm registry?

How can I revert a release?

If you have introduced a breaking bug in a release you have 2 options:

  • If you have a fix immediately ready, commit and push it (or merge it via a pull request) to the release branch

In both cases semantic-release will publish a new release, so your package users will get the fixed/reverted version.

In any case do not remove the Git tag associated with the buggy version, otherwise semantic-release will later try to republish that version. Publishing a version after un-publishing is not supported by most package managers.

Can I use .npmrc options?

How can I set the access level of the published npm package?

access=public

Or with the publishConfig.access key in your project's package.json:

{
  "publishConfig": {
    "access": "public"
  }
}

Can I use semantic-release to publish a package on Artifactory?

Can I manually trigger the release of a specific version?

You can trigger a release by pushing to your Git repository. You deliberately cannot trigger a specific version release, because this is the whole point of semantic-release.

Can I exclude commits from the analysis?

Yes, every commits that contains [skip release] or [release skip] in their message will be excluded from the commit analysis and won't participate in the release type determination.

How can I change the type of commits that trigger a release?

Commit

Release type

Commit with breaking change

Major Breaking release

Commit with type feat

Minor Feature release

Commit with type fix

Patch release

Commit with type perf

Patch release

Is it really a good idea to release on every push?

It is indeed a great idea because it forces you to follow best practices. If you don’t feel comfortable releasing every feature or fix on your master you might not treat your master branch as intended.

Branching is a core concept in Git, and the entire GitHub Flow is based upon it. There's only one rule: anything in the master branch is always deployable.

Can I set the initial release version of my package to 0.0.1?

Can I trust semantic-release with my releases?

Why does semantic-release require Node version >= 10.18?

Why does semantic-release require Git version >= 2.7.1?

What is npx?

Yes with the which prints to the console the next version to be published and the release notes.

If you are using a semantic-release installation and run multiple CI jobs with different versions, the yarn install command will fail on jobs running with Node < 8 as semantic-release requires and specifies it in its package.jsons key.

The recommended solution is to use the option to install the project dependencies on the CI environment, so Yarn will ignore the semantic-release's engines key:

Alternatively you can use a semantic-release installation and make sure to install and run the semantic-release command only in a CI jobs running with Node >= 10.18.

If your CI environment provides you can switch to Node 8 before installing and running the semantic-release command:

See the for more details on specific CI environments.

As semantic-release is recommended to be executed with an alternative is required for usage with Yarn. Even though it is possible to install npx with Yarn, it's not recommended. Yarn and npx would be using different cache locations.

For replace npx semantic-release with yarn run semantic-release.

For replace npx semantic-release with yarn global add semantic-release && semantic-release.

Use a semantic-release installation

Set semantic-release via

Make sure your CI job executing the semantic-release command has access to to execute the semantic-release command

See the for more details on specific CI environments.

In addition you will need to configure the semantic-release to disable the plugin which is used by default and use a plugin for your project type.

If there is no specific plugin for your project type you can use the plugin to publish the release with a shell command.

Here is a basic example to create and use a shell command to publish:

See the for more details on specific project types.

A way to set via environment variables

A way to guarantee that the semantic-release command is

See the for more details on specific CI environments.

Yes, you can by explicitly setting the option. You will also have to set the required via environment variables on your local machine, for example:

Yes, with the shareable configuration.

See the for the CI configuration.

By default semantic-release uses the plugin to publish a . For other Git hosted environment the and plugins can be used via .

See the plugins documentation for more details.

Yes, the publishing to the npm registry can be disabled with the option of the plugin. In addition the option allow to generate the package tarball in order to publish it to your repository with the or to a with the plugin.

See the plugin documentation for more details.

Otherwise, that introduced the bug and push the revert commit (or merge it via a pull request) to the release branch

Depending on the package manager you are using, you might be able to un-publish or deprecate a release, in order to prevent users from downloading it by accident. For example, npm allows you to after release. You may also a release if you would rather avoid un-publishing.

Note: If you are using the default be aware that it uses a different revert commit format than the standard one created by , contrary to what is . Therefore, if you revert a commit with , use the to format the message according to the . See for more details.

Yes, all the are supported via the file at the root of your repository.

See the plugin documentation for more details.

The can be set in the file at the root of your repository:

Any npm compatible registry is supported with the plugin. For Artifactory versions prior to 5.4, the legacy authentication has to be used (with NPM_USERNAME, NPM_PASSWORD and NPM_EMAIL ).

See for more details.

See documentation for Artifactiry configuration.

By default semantic-release uses the and triggers releases based on the following rules:

See the plugin documentation for more details.

This is fully customizable with the plugin's .

From :

If you need more control over the timing of releases, see for different options.

Note: Only the codebase changes altering the published package will trigger a release (for example new features, bug fixes or performance improvements would trigger a release while refactoring or changing code style would not). See for more details.

This is not supported by semantic-release as it's not considered a good practice, mostly because rules applies differently to major version zero.

If your project is under heavy development, with frequent breaking changes, and is not production ready yet we recommend .

See for more details on and the recommendation to start at version 1.0.0.

semantic-release has a full unit and integration test suite that tests npm publishes against the .

In addition the verifies that all necessary conditions for proceeding with a release are met, and a new release will be performed .

semantic-release is written using the latest features, without transpilation which requires Node version 10.18 or higher.

See for more details and solutions.

semantic-release uses Git CLI commands to read information about the repository such as branches, commit history and tags. Certain commands and options (such as or bug fixes related to git ls-files) used by semantic-release are only available in Git version 2.7.1 and higher.

– short for "npm exec" – is a CLI to find and execute npm binaries within the local node_modules folder or in the $PATH. If a binary can't be located npx will download the required package and execute it from its cache location. The tool is bundled with >= 5.2, or can be installed via npm install -g npx. For more details and motivation read the by .

npm
@semantic-release/git
npm
@semantic-release/npm
npm CLI
npm hook scripts
@semantic-release/git
@semantic-release/exec
Yarn
--ignore-engines
nvm
npx
@semantic-release/exec
GitHub releases
@semantic-release/gitlab-config
@semantic-release/github
GitHub release
@semantic-release/git
@semantic-release/changelog
plugins configuration
@semantic-release/git
@semantic-release/changelog
npmPublish
@semantic-release/npm
tarballDir
@semantic-release/git
GitHub release
@semantic-release/github
@semantic-release/npm
revert the commit
un-publish
within 72 hours
deprecate
Angular Commit Message Conventions
git revert
claimed in the convention
git revert
--edit option
Angular revert commit message format
conventional-changelog/conventional-changelog#348
npm configuration options
.npmrc
@semantic-release/npm
npm access option
.npmrc
@semantic-release/npm
environment variables
npm registry authentication
Artifactory - npm Registry
Angular Commit Message Conventions
@semantic-release/npm
@semantic-release/commit-analyzer
release-rules option
Understanding the GitHub Flow
Semantic Versioning
publishing pre-releases
“Introduction to SemVer” - Irina Gebauer
Semantic Versioning
npm-registry-couchapp
ECMAScript 2017
the --merged option of the git tag command
npx
npm
introductory blog post
@zkat
Node >= 10.18
How can I change the type of commits that trigger a release?
engines
Node >= 10.18
@semantic-release/npm
CI configuration recipes
CI configuration recipes
package managers and languages recipes
CI configuration recipes
plugins
dry-run options
options
CLI arguments or rc file
authentication
executed only after all the tests of all the jobs in the CI build pass
--no-ci CLI option
authentication
only if all your tests pass
Node version requirement
Triggering a release
verify conditions step
local
global
local installation
global installation
global
GitLab CI recipes