Workflow configuration
Last updated
Last updated
semantic-release allow to manage and automate complex release workflow, based on multiple Git branches and distribution channels. This allow to:
Distributes certain releases to a particular group of users via distribution channels
Manage the availability of releases on distribution channels via branches merge
Maintain multiple lines of releases in parallel
Work on large future releases outside the normal flow of one version increment per Git push
See Release workflow recipes for detailed examples.
The release workflow is configured via the branches option which accepts a single or an array of branch definitions. Each branch can be defined either as a string, a glob or an object. For string and glob definitions each property will be defaulted.
A branch can defined as one of three types:
release: to make releases on top of the last version released
maintenance: to make releases on top of an old release
pre-release: to make pre-releases
The type of the branch is automatically determined based on naming convention and/or properties.
A name
is required for any type of branch. It can be defined as a glob in which case the definition will be expanded to one per matching branch existing in the repository.
If name
doesn't match to any branch existing in the repository, the definition will be ignored. For example the default configuration includes the definition next
and next-major
which will become active only when the branches next
and/or next-major
are created in the repository. This allow to define your workflow once with all potential branches you might use and have the effective configuration evolving as you create new branches.
For example the configuration ['+([0-9])?(.{+([0-9]),x}).x', 'master', 'next']
will be expanded as:
The channel
can be defined for any branch type. By default releases will be done on the default distribution channel (for example the @latest
dist-tag for npm) for the first release branch and on a distribution channel named based on the branch name
for any other branch. If the channel
property is set to false
the default channel will be used.
The value of channel
, if defined as a string, is generated with Lodash template with the variable name
available.
For example the configuration ['master', {name: 'next', channel: 'channel-${name}'}]
will be expanded as:
A range
only applies to maintenance branches, is required and must be formatted like N.N.x
or N.x
(N
is a number). In case the name
is formatted as a range (for example 1.x
or 1.5.x
) the branch will be considered a maintenance branch and the name
value will be used for the range
.
For example the configuration ['1.1.x', '1.2.x', 'master']
will be expanded as:
A prerelease
property applies only to pre-release branches and the prerelease
value must be valid per the Semantic Versioning Specification. It will determine the name of versions (for example if prerelease
is set to beta
the version be formatted like 2.0.0-beta.1
, 2.0.0-beta.2
etc...). If the prerelease
property is set to true
the name
value will be used.
The value of prerelease
, if defined as a string, is generated with Lodash template with the variable name
available.
For example the configuration ['master', {name: 'pre/rc', prerelease: '${name.replace(/^pre\\//g, "")}'}, {name: 'beta', prerelease: true}]
will be expanded as:
A release branch is the base type of branch used by semantic-release that allows to publish releases with a semantic version, optionally on a specific distribution channel. Distribution channels (for example npm dist-tags or Chrome release channels) are a way to distribute new releases only to a subset of users in order to get early feedback. Later on, those releases can be added to the general distribution channel to be made available to all users.
semantic-release will automatically add releases to the corresponding distribution channel when code is merged from a release branch to another.
A project must define a minimum of 1 release branch and can have a maximum of 3. The order of the release branch definitions is significant, as versions released on a given branch must always be higher than the last release made on the previous branch. This allow to avoid situation that would lead to an attempt to publish releases with the same version number but different codebase. When multiple release branches are configured and a commit that would create a version conflict is pushed, semantic-release will not perform the release and will throw an EINVALIDNEXTVERSION
error, listing the problematic commits and the valid branches on which to move them.
Note: With semantic-release as with most package managers, a release version must be unique, independently of the distribution channel on which it is available.
See publishing on distribution channels recipe for a detailed example.
With the configuration "branches": ["master", "next"]
, if the last release published from master
is 1.0.0
and the last one from next
is 2.0.0
then:
Only versions in range 1.x.x
can be published from master
, so only fix
and feat
commits can be pushed to master
Once next
get merged into master
the release 2.0.0
will be made available on the channel associated with master
and both master
and next
will accept any commit type
This verification prevent scenario such as: 1. Create a feat
commit on next
which triggers the release of version 1.0.0
on the next
channel 2. Merge next
into master
which adds 1.0.0
on the default channel 3. Create a feat
commit on next
which triggers the release of version 1.1.0
on the next
channel 4. Create a feat
commit on master
which would attempt to release the version 1.1.0
on the default channel
In step 4 semantic-release will throw an EINVALIDNEXTVERSION
error to prevent the attempt at releasing version 1.1.0
which was already released on step 3 with a different codebase. The error will indicate that the commit should be created on next
instead. Alternatively if the next
branch is merged into master
, the version 1.1.0
will be made available on the default channel and the feat
commit would be allowed on master
to release 1.2.0
.
When merging commits associated with a release from one release branch to another, semantic-release will make the corresponding version available on the channel associated with the target branch.
When merging commits not associated with a release, commits from a maintenance branch or commits from a pre-release branch semantic-release will treat them as pushed commits and publish a new release if necessary.
A maintenance branch is a type of branch used by semantic-release that allows to publish releases with a semantic version on top of the codebase of an old release. This is useful when you need to provide fixes or features to users who cannot upgrade to the last version of your package.
A maintenance branch is characterized by a range which defines the versions that can be published from it. The range
value of each maintenance branch must be unique across the project.
semantic-release will always publish releases to a distribution channel specific to the range, so only the users who choose to use that particular line of versions will receive new releases.
Maintenance branches are always considered lower than release branches and similarly to them, when a commit that would create a version conflict is pushed, semantic-release will not perform the release and will throw an EINVALIDNEXTVERSION
error, listing the problematic commits and the valid branches on which to move them.
semantic-release will automatically add releases to the corresponding distribution channel when code is merged from a release or maintenance branch to another maintenance branch, however only versions within the branch range
can be merged. If a merged version is outside the maintenance branch range
, semantic-release will not add to the corresponding channel and will throw an EINVALIDMAINTENANCEMERGE
error.
See publishing maintenance releases recipe for a detailed example.
With the configuration "branches": ["1.0.x", "1.x", "master"]
, if the last release published from master
is 1.5.0
then:
Only versions in range >=1.0.0 <1.1.0
can be published from 1.0.x
, so only fix
commits can be pushed to 1.0.x
Only versions in range >=1.1.0 <1.5.0
can be published from 1.x
, so only fix
and feat
commits can be pushed to 1.x
as long the resulting release is lower than 1.5.0
Once 2.0.0
is released from master
, versions in range >=1.1.0 <2.0.0
can be published from 1.x
, so any number of fix
and feat
commits can be pushed to 1.x
With the configuration "branches": ["1.0.x", "1.x", "master"]
, if the last release published from master
is 1.0.0
then:
Creating the branch 1.0.x
from master
will make the 1.0.0
release available on the 1.0.x
distribution channel
Pushing a fix
commit on the 1.0.x
branch will release the version 1.0.1
on the 1.0.x
distribution channel
Creating the branch 1.x
from master
will make the 1.0.0
release available on the 1.x
distribution channel
Merging the branch 1.0.x
into 1.x
will make the version 1.0.1
available on the 1.x
distribution channel
A pre-release branch is a type of branch used by semantic-release that allows to publish releases with a pre-release version. Using a pre-release version allow to publish multiple releases with the same version. Those release will be differentiated via their identifiers (in 1.0.0-alpha.1
the identifier is alpha.1
). This is useful when you need to work on a future major release that will include many breaking changes but you do not want to increment the version number for each breaking change commit.
A pre-release branch is characterized by the prerelease
property that defines the static part of the version released (in 1.0.0-alpha.1
the static part fo the identifier is alpha
). The prerelease
value of each pre-release branch must be unique across the project.
semantic-release will always publish pre-releases to a specific distribution channel, so only the users who choose to use that particular line of versions will receive new releases.
When merging commits associated with an existing release, semantic-release will treat them as pushed commits and publish a new release if necessary, but it will never add those releases to the distribution channel corresponding to the pre-release branch.
See publishing pre-releases recipe for a detailed example.
With the configuration "branches": ["master", {"name": "beta", "prerelease": true}]
, if the last release published from master
is 1.0.0
then:
Pushing a BREAKING CHANGE
commit on the beta
branch will release the version 2.0.0-beta.1
on the beta
distribution channel
Pushing either a fix
, feat
or a BREAKING CHANGE
commit on the beta
branch will release the version 2.0.0-beta.2
(then 2.0.0-beta.3
, 2.0.0-beta.4
, etc...) on the beta
distribution channel
With the configuration "branches": ["master", {"name": "beta", "prerelease": true}]
, if the last release published from master
is 1.0.0
and the last one published from beta
is 2.0.0-beta.1
then:
Pushing a fix
commit on the master
branch will release the version 1.0.1
on the default distribution channel
Merging the branch master
into beta
will release the version 2.0.0-beta.2
on the beta
distribution channel
Property
Branch type
Description
Default
name
All
Required. The Git branch holding the commits to analyze and the code to release. See name.
- The value itself if defined as a String
or the matching branches name if defined as a glob.
channel
All
The distribution channel on which to publish releases from this branch. Set to false
to force the default distribution channel instead of using the default. See channel.
undefined
for the first release branch, the value of name
for subsequent ones.
range
maintenance only
Required unless name
is formatted like N.N.x
or N.x
(N
is a number). The range of semantic versions to support on this branch. See range.
The value of name
.
prerelease
pre-release only
Required. The pre-release denotation to append to semantic versions released from this branch. See prerelease.
-