Release Workflow Configuration

semantic-release enables managing and automating complex release workflows, based on multiple Git branches and distribution channels. This enables:

• Distributing certain releases to a particular group of users via distribution channels
• Managing the availability of releases on distribution channels via branch merges
• Maintaining multiple lines of releases in parallel
• Working 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 either a single branch definition or an array of branch definitions. Each branch can be defined as a string, a glob, or an object. For string and glob definitions, defaults are applied to each property.

A branch can be 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 conventions and/or properties.

Branch Properties

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

name

type: String, Glob
branch type: All
default: The value itself if defined as a String, or the matching branch name if defined as a glob.

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 any branch that exists in the repository, the definition will be ignored. For example, the default configuration includes the definitions next and next-major, which become active only when the branches next and/or next-major are created in the repository. This allows you to define your workflow once with all potential branches you might use and have the effective configuration evolve as you create new branches.

For example the configuration ['+([0-9])?(.{+([0-9]),x}).x', 'master', 'next'] will be expanded as:

{
  branches: [
    { name: "1.x", range: "1.x", channel: "1.x" }, // Only after the `1.x` is created in the repo
    { name: "2.x", range: "2.x", channel: "2.x" }, // Only after the `2.x` is created in the repo
    { name: "master" },
    { name: "next", channel: "next" }, // Only after the `next` is created in the repo
  ];
}

channel

type: String, Boolean
branch type: All
default: undefined for the first release branch; the value of name for subsequent ones.

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:

{
  branches: [
    { name: "master" }, // `channel` is undefined so the default distribution channel will be used
    { name: "next", channel: "channel-next" }, // `channel` is built with the template `channel-${name}`
  ];
}

range

type: String
branch type: Maintenance only
default: The value of name.

A range only applies to maintenance branches, is required (unless name is formatted like N.N.x or N.x), 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:

{
  branches: [
    { name: "1.1.x", range: "1.1.x", channel: "1.1.x" },
    { name: "1.2.x", range: "1.2.x", channel: "1.2.x" },
    { name: "master" },
  ];
}

prerelease

type: String, Boolean
branch type: Pre-release only
default: -

A prerelease property applies only to pre-release branches and is required. The prerelease value must be valid per the Semantic Versioning Specification. It determines the format of versions (for example, if prerelease is set to beta, versions will 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:

{
  branches: [
    { name: "master" },
    { name: "pre/rc", channel: "pre/rc", prerelease: "rc" }, // `prerelease` is built with the template `${name.replace(/^pre\\//g, "")}`
    { name: "beta", channel: "beta", prerelease: true }, // `prerelease` is set to `beta` as it is the value of `name`
  ];
}

Branch types

Release branches

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 allows avoiding situations that would lead to attempts to publish releases with the same version number but different codebases. 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.

Pushing to a release branch

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 gets 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 prevents scenarios 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.

Merging into a release branch

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.

Maintenance branches

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.

Pushing to a maintenance branch

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

Merging into a maintenance branch

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

Pre-release branches

A pre-release branch is a type of branch used by semantic-release that allows publishing releases with a pre-release version. Using a pre-release version allows publishing multiple releases with the same version. Those releases are 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 of 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.

Pushing to a pre-release branch

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

Merging into a pre-release branch

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