Configuration

Last updated last month

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 three 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

Via .releaserc file:

{
"branch": "next"
}
$ semantic-release

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

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

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

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.

Options

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.

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

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.

dryRun

Type: Boolean Default: false if running in a CI environment, true 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. This allows for making releases from a local machine.

debug

Type: Boolean Default: false CLI argument: --debug

Output debugging information. It can also be enabled by setting 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.

analyzeCommits

Type: Array, 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: Array, String, Object Default: ['@semantic-release/release-notes-generator'] CLI argument: --generate-notes

Define the generate notes plugins.

See Plugins configuration for more details.

prepare

Type: Array, String, Object Default: ['@semantic-release/npm'] CLI argument: --prepare

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

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.

success

Type: Array, String, Object Default: ['@semantic-release/github'] CLI argument: --success

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

See Plugins configuration for more details.

fail

Type: Array, String, Object Default: ['@semantic-release/github'] CLI argument: --fail

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

See Plugins configuration for more details.