Configuration
semantic-release configuration consists of:
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.
- A
.releaserc
file, written in YAML or JSON, with optional extensions:.yaml
/.yml
/.json
/.js
/.cjs
- A
release.config.(js|cjs)
file that exports an object - A
release
key in the project'spackage.json
file
Alternatively, some options can be set via CLI arguments.
The following three examples are the same.
- Via
release
key in the project'spackage.json
file:
{
"release": {
"branches": ["master", "next"]
}
}
- Via
.releaserc
file:
{
"branches": ["master", "next"]
}
- Via
release.config.cjs
file:
/**
* @type {import('semantic-release').GlobalConfig}
*/
module.exports = {
branches: ["master", "next"],
};
- Via CLI argument:
$ semantic-release --branches next
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
file, the configuration must be set without a release
property.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.
Type:
Array
, String
, Object
Default: ['+([0-9])?(.{+([0-9]),x}).x', 'master', '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
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
orN.x.x
orN.x
withN
being a number) - regular releases to the
next
distribution channel from the branchnext
if it exists - regular releases to the
next-major
distribution channel from the branchnext-major
if it exists - pre-releases to the
beta
distribution channel from the branchbeta
if it exists - pre-releases to the
alpha
distribution channel from the branchalpha
if it exists
Note: 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 master
branch.Note: 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 protected branches.
Type:
String
Default: repository
property in package.json
or git origin url
CLI arguments: -r
, --repository-url
The git repository URL.
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.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 steps if they implement it.
Plugins configuration can defined by wrapping the name and an options object in an array.
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 steps: 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.
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
.Type:
Boolean
Default: false
CLI argument: --debug
Output debugging information. This can also be enabled by setting the
DEBUG
environment variable to semantic-release:*
.Note: The
debug
is used only supported via CLI argument. To enable debug mode from the JS API use require('debug').enable('semantic-release:*')
.Variable | Description | Default |
---|---|---|
GIT_AUTHOR_NAME | @semantic-release-bot. | |
GIT_AUTHOR_EMAIL | @semantic-release-bot email address. | |
GIT_COMMITTER_NAME | @semantic-release-bot. | |
GIT_COMMITTER_EMAIL | @semantic-release-bot email address. |
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 release branches history and is tagged with the version released, formatted according to the tag format configured (defaults to
vx.y.z
).For example, if your release branch is
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 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
Last modified 5m ago