semantic-release/docs/usage/configuration.md

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

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.