Configuration

Configure semantic-release options, plugins, and release branches via config files, CLI arguments, or shareable configurations.

semantic-release configuration consists of:

• Git repository (URL and options release branches and tag format)
• Plugins declaration and options
• Run mode (debug, dry run and local (no CI))

All of these options can be configured through config file, CLI arguments or by extending a shareable configuration.

Additionally, metadata of Git tags generated by semantic-release can be customized via standard Git environment variables.

Configuration file

semantic-release’s options, mode and plugins can be set via either:

• A .releaserc file, written in YAML or JSON, with optional extensions: .yaml/.yml/.json/.js/.ts/.cjs/.mjs
• A release.config.(js|ts|cjs|mjs) file that exports an object
• A release key in the project’s package.json file

The following three examples are the same. Use master instead of main if your default branch is master.

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

  {
    "release": {
      "branches": ["main", "next"]
    }
  }

• Via .releaserc file:

  {
    "branches": ["main", "next"]
  }

• Via release.config.cjs file:

  /**
   * @type {import('semantic-release').GlobalConfig}
   */
  module.exports = {
    branches: ["main", "next"],
  };

• Via release.config.mjs file:

  /**
   * @type {import('semantic-release').GlobalConfig}
   */
  export default {
    branches: ["main", "next"],
  };

Note

When configuring via package.json, the configuration must be under the release property. However, when using a .releaserc or a release.config.** file, the configuration must be set without a release property.

CLI arguments

Some options can also be passed as command-line arguments to the semantic-release command.

$ semantic-release --branches next

Note

• CLI arguments take precedence over options configured in the configuration file.
• Plugin options cannot be configured through CLI arguments. See plugins for details.

Options

The following are semantic-release options you can set in the configuration file, pass as CLI arguments, or define in a shareable configuration.

extends

type: Array, String
CLI arguments: -e, --extends

List of modules or file paths containing a shareable configuration. If multiple shareable configurations 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.

branches

type: Array, String, Object
default: ['+([0-9])?(.{+([0-9]),x}).x', 'master', 'main', 'next', 'next-major', {name: 'beta', prerelease: true}, {name: 'alpha', prerelease: true}]
CLI arguments: --branches

The branches on which releases should happen. By default semantic-release will release:

• regular releases to the default distribution channel from the branch main or master
• regular releases to a distribution channel matching the branch name from any existing branch with a name matching a maintenance release range (N.N.x or N.x.x or N.x with N being a number)
• regular releases to the next distribution channel from the branch next if it exists
• regular releases to the next-major distribution channel from the branch next-major if it exists
• pre-releases to the beta distribution channel from the branch beta if it exists
• pre-releases to the alpha distribution channel from the branch alpha if it exists

Note

• Branches configuration key accepts micromatch globs.
• If your repository does not have a release branch, then semantic-release will fail with an ERELEASEBRANCHES error message. If you are using the default configuration, you can fix this error by pushing a main or master branch.
• Once semantic-release is configured, any user with the permission to push commits on one of those branches will be able to publish a release. It is recommended to protect those branches, for example with GitHub rulesets.

See Workflow configuration for more details.

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

tagFormat

type: String
default: v${version}
CLI arguments: -t, --tag-format

The Git tag format used by semantic-release to identify releases. The tag name is generated with Lodash template and will be compiled with the version variable.

Note

The tagFormat must contain the version variable exactly once and compile to a valid Git reference.

plugins

type: Array
default: ['@semantic-release/commit-analyzer', '@semantic-release/release-notes-generator', '@semantic-release/npm', '@semantic-release/github']
CLI arguments: -p, --plugins

Define the list of plugins to use. Plugins will run in series, in the order defined, for each release step whose lifecycle hook they implement.

Plugins configuration can defined by wrapping the name and an options object in an array.

Note

While plugins can be listed by name via the --plugins CLI argument, individual plugin options cannot be configured through CLI arguments. If you need to configure plugin options beyond specifying which plugins to use, a configuration file is required.

See Plugins for more details.

dryRun

type: Boolean
default: false if running in a CI environment, true otherwise
CLI arguments: -d, --dry-run

The objective of the dry-run mode is to get a preview of the pending release. Dry-run mode skips the following lifecycle hooks: prepare, publish, addChannel, success, and fail. In addition to this it prints the next version and release notes to the console.

Note

The Dry-run mode verifies the repository push permission, even though nothing will be pushed. The verification is done to help user to figure out potential configuration issues.

ci

type: Boolean
default: true
CLI arguments: --ci / --no-ci

Set to false to skip Continuous Integration environment verifications. This allows for making releases from a local machine.

Note

The CLI arguments --no-ci is equivalent to --ci false.

debug

type: Boolean
default: false
CLI arguments: --debug

Output debugging information. This can also be enabled by setting the DEBUG environment variable to semantic-release:*.

Note

The debug option is only supported via CLI argument. To enable debug mode from the JS API use require('debug').enable('semantic-release:*').

Git environment variables

Variable	Description	Default
GIT_AUTHOR_NAME	The author name associated with the Git release tag. See Git environment variables.	@semantic-release-bot.
GIT_AUTHOR_EMAIL	The author email associated with the Git release tag. See Git environment variables.	@semantic-release-bot email address.
GIT_COMMITTER_NAME	The committer name associated with the Git release tag. See Git environment variables.	@semantic-release-bot.
GIT_COMMITTER_EMAIL	The committer email associated with the Git release tag. See Git environment variables.	@semantic-release-bot email address.

Existing version tags

semantic-release uses Git tags to determine the commits added since the last release. If a release has been published before setting up semantic-release you must make sure the most recent commit included in the last published release is in the history of the release branch(es) and is tagged with the version released, formatted according to the tag format configured (defaults to vx.y.z).

If the previous releases were published with npm publish this should already be the case.

For example, if your release branch is main/master, the last release published on your project is 1.1.0 and the last commit included has the sha 1234567, you must make sure this commit is in main/master history and is tagged with v1.1.0.

# Make sure the commit 1234567 is in the release branch history
$ git branch --contains 1234567

# If the commit is not in the branch history it means that either:
# - you use a different branch than the one your release from before
# - or the commit sha has been rewritten (with git rebase)
# In both cases you need to configure your repository to have the last release commit in the history of the release branch

# List the tags for the commit 1234567
$ git tag --contains 1234567

# If v1.1.0 is not in the list you add it with
$ git tag v1.1.0 1234567
$ git push origin v1.1.0