semantic-release/README.md

📦🚀 semantic-release

Fully automated version management and package publishing.

semantic-release automates the whole package release workflow including: determining the next version number, generating the release notes and publishing the package. This removes the immediate connection between human emotions and version numbers, strictly following the Semantic Versioning specification.

Trust us, this will change your workflow for the better. – egghead.io

Highlights

• Fully automated release
• Enforce Semantic Versioning specification
• New features and fixes are immediately available to users
• Use formalized commit message convention to document changes in the codebase
• Integrate with your continuous integration workflow
• Avoid potential errors associated with manual releases
• Support any package managers and languages via plugins
• Simple and reusable configuration via shareable configurations

Table of Contents

• How does it work?
• Installation and Usage
• Plugins
• Shareable configurations
• Recipes
• Frequently Asked Questions
• Resources
• Support
• Badge
• Node Support Policy
• Team

How does it work?

Commit message format

semantic-release uses the commit messages to determine the type of changes in the codebase. Following formalized conventions for commit messages, semantic-release automatically determines the next semantic version number, generates a changelog and publish the release.

By default semantic-release uses Angular Commit Message Conventions. The commit message format that can changed with the preset or config options of the @semantic-release/commit-analyzer and @semantic-release/release-notes-generator plugins.

Tools such as commitizen, commitlint or semantic-git-commit-cli can be used to help contributor and enforce valid commits message.

Here is an example of the release type that will be done based on a commit messages:

Commit message	Release type
fix(pencil): stop graphite breaking when too much pressure applied	Patch Release
feat(pencil): add 'graphiteWidth' option	Minor Feature Release
perf(pencil): remove graphiteWidth option BREAKING CHANGE: The graphiteWidth option has been removed. The default graphite width of 10mm is always used for performance reasons.	Major Breaking Release

Automation with CI

semantic-release is meant to be executed on the CI environment after every successful build on the release branch. This way no human is directly involved in the release process and the releases are guaranteed to be unromantic and unsentimental.

Triggering a release

When pushing new commits to the release branch (i.e. master) with git push or by merging a pull request or merging from another branch, a CI build is triggered and runs the semantic-release command to make a release if there is relevant codebase changes since the last release.

By default a release will be done for each push to the release branch that contains relevant code changes. If you need more control over the timing of releases you have a couple of options:

• Publish releases on a distribution channel (for example npm’s dist-tags). This way you can keep control over what your users end up using by default, and you can decide when to make an automatically released version available to the stable channel, and promote it.
• Develop on a dev branch and merge it to the release branch (i.e. master) once you are ready to publish. semantic-release will run only on pushes to the release branch.

Release steps

After running the tests the command semantic-release will execute the following steps:

Step	Description
Verify Conditions	Verify all the conditions to proceed with the release with the verify conditions plugins.
Get last release	Obtain last release with the get last release plugin.
Analyze commits	Determine the type of release to do with the analyze commits plugin based on the commits added since the last release.
Verify release	Verify the release conformity with the verify release plugins.
Generate notes	Generate release notes with the generate notes plugin for the commits added since the last release.
Publish	Publish the release with the publish plugins.

Installation and Usage

Local installation

For Node modules projects we recommend to install semantic-release locally and to run the semantic-release command with a npm script:

$ npm install --save-dev semantic-release

In your package.json:

"scripts": {
  "semantic-release": "semantic-release"
}

Then in the CI environment:

$ npm run semantic-release

Global installation

For other type of projects we recommend to install semantic-release globally directly in the CI environment:

$ npm install -g semantic-release
$ semantic-release

CI configuration

Run semantic-release only after all tests succeeded

The semantic-release command must be executed only after all the tests in the CI build pass. If the build runs multiple jobs (for example to test on multiple Operating Systems or Node versions) the CI has to be configured to guarantee that the semantic-release command is executed only after all jobs are successful. This can be achieved with Travis Build Stages, CircleCI Workflows, Codeship Deployment Pipelines, GitLab Pipelines, Wercker Workflows, GoCD Pipelines or specific tools like travis-deploy-once.

See CI configuration recipes for more details.

Authentication

Most semantic-release plugins require to set up authentication in order to publish to your package manager's registry or to access your project's Git hosted service. The authentication token/credentials have to be made available in the CI serice via environment variables.

See each plugin documentation for the environment variable to set up.

The default npm and github plugins require the following environment variables:

Variable	Description
NPM_TOKEN	npm token created via npm token create. Note: Only the auth-only level of npm two-factor authentication is supported.
GH_TOKEN	GitHub authentication token. Note: Only the personal token authentication is supported.

See CI configuration recipes for more details on how to configure environment variables in your CI service.

Automatic setup with semantic-release-cli

semantic-release-cli allow to easily install semantic-release in your Node project and set up the CI configuration:

npm install -g semantic-release-cli

cd your-module
semantic-release-cli setup

See the semantic-release-cli documentation for more details.

Configuration

In order to customize semantic-release’s behavior, options and plugins can be set via:

• A .releaserc file, written in YAML or JSON, with optional extensions: .yaml/.yml/.json/.js
• A release.config.js file that exports an object
• A release key in the project's package.json file
• CLI arguments

The following two examples are the same.

Via CLI argument:

$ semantic-release --branch next

Via release key in the project's package.json file:

"release": {
  "branch": "next"
}

$ semantic-release

Note: CLI arguments take precedence over options configured in the configuration file.

Note: Plugins options cannot be defined via CLI arguments and must be defined in the configuration file.

Options

extends

Type: Array, String

CLI arguments: -e, --extends

List of modules or file paths containing a shareable configuration. If multiple shareable configuration are set, they will be imported in the order defined with each configuration option taking precedence over the options defined in a previous shareable configuration.

Note: Options defined via CLI arguments or in the configuration file will take precedence over the ones defined in any shareable configuration.

branch

Type: String

Default: master

CLI arguments: -b, --branch

The branch on which releases should happen.

repositoryUrl

Type: String

Default: repository property in package.json or git origin url

CLI arguments: -r, --repository-url

The git repository URL

Any valid git url format is supported (See Git protocols).

Note: If the Github plugin is used the URL must be a valid Github URL that include the owner, the repository name and the host. The Github shorthand URL is not supported.

dryRun

Type: Boolean

Default: false if running in a CI environment, false otherwise

CLI arguments: -d, --dry-run

Dry-run mode, skip publishing, print next version and release notes.

noCi

Type: Boolean

Default: false

CLI arguments: --no-ci

Skip Continuous Integration environment verifications, allowing to make releases from a local machine.

debug

Type: Boolean

Default: false

CLI argument: --debug

Output debugging information. It can also be enabled by set the DEBUG environment variable to semantic-release.

verifyConditions

Type: Array, String, Object

Default: ['@semantic-release/npm', '@semantic-release/github']

CLI argument: --verify-conditions

Define the list of verify conditions plugins. Plugins will run in series, in the order defined in the Array.

See Plugins configuration for more details.

getLastRelease

Type: String, Object

Default: ['@semantic-release/npm']

CLI argument: --get-last-release

Define the get last release plugin.

See Plugins configuration for more details.

analyzeCommits

Type: String, Object

Default: ['@semantic-release/commit-analyzer']

CLI argument: --analyze-commits

Define the analyze commits plugin.

See Plugins configuration for more details.

verifyRelease

Type: Array, String, Object

Default: []

CLI argument: --verify-release

Define the list of verify release plugins. Plugins will run in series, in the order defined in the Array.

See Plugins configuration for more details.

generateNotes

Type: String, Object

Default: ['@semantic-release/release-notes-generator']

CLI argument: --generate-notes

Define the generate notes plugin.

See Plugins configuration for more details.

publish

Type: Array, String, Object

Default: ['@semantic-release/npm', '@semantic-release/github']

CLI argument: --publish

Define the list of publish plugins. Plugins will run in series, in the order defined in the Array.

See Plugins configuration for more details.

Plugins

Each release steps is implemented within a plugin or a list of plugins that can be configured, allowing to support different commit message format, release not generator and publishing platforms.

See List of semantic-release plugins.

See Plugin developer Guide for more information on how to develop a plugin.

Plugin types

verifyConditions plugin

Plugin responsible for verifying all the conditions to proceed with the release: configuration is correct, authentication token are valid, etc...

Default implementation: npm and github.

getLastRelease plugin

Plugin responsible for determining the version of the package last release.

Default implementation: @semantic-release/npm.

analyzeCommits plugin

Plugin responsible for determining the type of the next release (major, minor or patch).

Default implementation: @semantic-release/commit-analyzer.

verifyRelease plugin

Plugin responsible for verifying the parameters (version, type, dist-tag etc...) of the release that is about to be published match certain expectations. For example the cracks plugin allows to verify that if a release contains breaking changes, its type must be major.

Default implementation: none.

generateNotes plugin

Plugin responsible for generating release notes.

Default implementation: @semantic-release/release-notes-generator.

publish plugin

Plugin responsible for publishing the release.

Default implementation: npm and github.

Plugins configuration

Plugin can be configured by specifying the plugin's module name or file path directly as a String or within the path key of an Object.

Plugins specific options can be set similarly to the other semantic-release options or within the plugin Object. Plugins options defined along the other semantic-release options will apply to all plugins, while the one defined within the plugin Object will apply only to this specific plugin.

For example:

{
  "release": {
    "verifyConditions": [
      {
        "path": "@semantic-release/exec",
        "cmd": "verify-conditions.sh"
      },
      "@semantic-release/npm",
      "@semantic-release/github"
    ],
    "analyzeCommits": "custom-plugin",
    "verifyRelease": [
      {
        "path": "@semantic-release/exec",
        "cmd": "verify-release.sh"
      },
    ],
    "generateNotes": "./build/my-plugin.js",
    "githubUrl": "https://my-ghe.com",
    "githubApiPathPrefix": "/api-prefix"
  }
}

With this configuration:

• the custom-plugin npm module will be used to analyze commits
• the ./build/my-plugin.js script will be used to generate release notes
• the @semantic-release/exec, @semantic-release/npm and @semantic-release/exec plugins will be used to verify conditions
• the @semantic-release/exec plugin will be used to verify the release
• the cmd option will be set to verify-conditions.sh only for the @semantic-release/exec plugin used to verify conditions
• the cmd option will be set to verify-release.sh only for the @semantic-release/exec plugin used to verify the release
• the githubUrl and githubApiPathPrefix options will be set to respectively https://my-ghe.com and /api-prefix for all plugins

Shareable configurations

A sharable configuration is an npm package that exports a semantic-release configuration object. It allows to easily use the same configuration across several projects.

The shareable configurations to use can be set with the extends option.

See List of semantic-release shareable configuration.

See Shareable configuration developer Guide for more information on how to develop a shareable configuration.

Recipes

• CI configurations
• Package managers and languages

Frequently Asked Questions

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 npm.

By default, only the published package will contains 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 @semantic-release/git 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 npm, therefore it won't be available for scripts ran before the semantic-release command.

As semantic-release uses the npm CLI to publish, all npm hook scripts will be executed. Therefore you can run your build script in the prepublishOnly hook. It will be executed after the semantic-release command update the package.json’s version and before publishing.

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

Yes with the dry-run options which prints to the console the next version to be published and the release notes.

Can I use semantic-release with Yarn?

If you are using a local semantic-release installation and run multiple CI jobs with different versions, the yarn install command will fail with Node < 8 as semantic-release require Node >= 8. See yarnpkg/rfcs#69.

In order to run semantic-release with Yarn you would need to:

• Use a global semantic-release installation
• Make sure to install and run the semantic-release command only in a CI jobs running with Node >= 8

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

$ nvm install 8 && yarn install -g semantic-release && semantic-release

See the CI configuration recipes for more details on specific CI environments.

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-JavaScript package you would need to:

• Use a global semantic-release installation
• Set semantic-release options via CLI arguments or rc file
• Make sure your CI job executing the semantic-release command has access to Node >= 8 to execute the semantic-release command

See the CI configuration recipes for more details on specific CI environments.

Can I use semantic-release with any CI service?

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

• A way to set authentication via environment variables
• A way to guarantee that the semantic-release command is executed only after all the tests of all the jobs in the CI build pass

See the CI configuration recipes for more details on specific CI environments.

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

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

$ NPM_TOKEN=<your_npm_token> GH_TOKEN=<your_github_token> npm run 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?

Yes, with the @semantic-release/gitlab-config shareable configuration.

See the GitLab CI recipes for the CI configuration.

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

By default semantic-release uses the @semantic-release/github plugin to publish a GitHub release. For other Git hosted environment the @semantic-release/git and @semantic-release/changelog plugins can be used via plugins configuration.

See the @semantic-release/git @semantic-release/changelog plugins documentation for more details.

Can I skip the release to the npm registry?

Yes, the publishing to the npm registry can be disabled with the npmPublish option of the @semantic-release/npm plugin. In addition the tarballDir option allow to generate the package tarball in order to publish it to your repository with the @semantic-release/git or to a GitHub release with the @semantic-release/github plugin.

See the @semantic-release/npm plugin documentation for more details.

Can I use .npmrc options?

Yes, all the npm configuration options are supported via the .npmrc file at the root of your repository.

See the @semantic-release/npm plugin documentation for more details.

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

The npm access option can be set in the .npmrc file at the root of your repository:

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?

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

See npm registry authentication for more details.

See Artifactory - npm Registry documentation for Artifactiry configuration.

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.

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.

From Understanding the GitHub Flow:

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.

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

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

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

In early development phase when your package is not ready for production yet we recommend to publish releases on a distribution channel (for example npm’s dist-tags) or to develop on a dev branch and merge it to master periodically. See Triggering a release for more details on those solutions.

See “Introduction to SemVer” - Irina Gebauer for more details on Semantic Versioning and the recommendation to start at version 1.0.0.

Can I trust semantic-release with my releases?

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

In addition the verify conditions step verifies that all necessary conditions for proceeding with a release are met, and a new release will be performed only if all your tests pass.

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

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

See Node version requirement for more details and solutions.

Resources

Videos

• "Introducing Reliable Dependency and Release Management for npm Packages" - Gregor Martynus
• "Kill all humans" - Jan Lehnardt
• Publishing JavaScript Packages" - JavaScript Air
• "Managing Dependencies like a boss 😎" - JavaScript Air
• "Dependency Hell Just Froze Over" - Stephan Bönnemann
• “semantic-release Q&A with Kent C. Dodds”
• “We fail to follow SemVer – and why it needn’t matter” - Stephan Bönnemann

Articles

• “Introduction to SemVer” - Irina Gebauer

Tutorials

• “How to Write a JavaScript Library - Automating Releases with semantic-release” – egghead.io

Support

• Stack Overflow
• Gitter chat
• Twitter

Badge

Let people know that your package is published using semantic-release by including this badge in your readme.

[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)

Node Support Policy

We only support Long-Term Support versions of Node starting with Node 8.9.0 (LTS).

We specifically limit our support to LTS versions of Node, not because this package won't work on other versions, but because we have a limited amount of time, and supporting LTS offers the greatest return on that investment.

It's possible this package will work correctly on newer versions of Node. It may even be possible to use this package on older versions of Node, though that's more unlikely as we'll make every effort to take advantage of features available in the oldest LTS version we support.

As each Node LTS version reaches its end-of-life we will remove that version from the node engines property of our package's package.json file. Removing a Node version is considered a breaking change and will entail the publishing of a new major version of this package. We will not accept any requests to support an end-of-life version of Node. Any merge requests or issues supporting an end-of-life version of Node will be closed.

We will accept code that allows this package to run on newer, non-LTS, versions of Node. Furthermore, we will attempt to ensure our own changes work on the latest version of Node. To help in that commitment, our continuous integration setup runs against all LTS versions of Node in addition the most recent Node release; called current.

JavaScript package managers should allow you to install this package with any version of Node, with, at most, a warning if your version of Node does not fall within the range specified by our node engines property. If you encounter issues installing this package, please report the issue to your package manager.

Team

Stephan Bönnemann	Rolf Erik Lekang	Johannes Jörg Schmidt	Gregor Martynus	Finn Pauls	Pierre Vanduynslager	Christoph Witzko