Plugins

Plugins let semantic-release extend release steps through configurable lifecycle methods. Core owns the release lifecycle, exposes lifecycle hooks for selected release steps, and invokes plugin methods bound to those hooks.

This enables support for different commit message conventions, release note generators, and publishing platforms.

A plugin is a npm module that can implement one or more lifecycle methods for the following hooks:

Lifecycle Hook	Related Release Step	Required	Description
`verifyConditions`	Verify Conditions	No	Verify conditions necessary to proceed with the release: configuration is correct, authentication tokens are valid, and so on.
`analyzeCommits`	Analyze Commits	Yes	Determine the type of the next release (`major`, `minor`, or `patch`). This hook is required to decide the next release type. If multiple plugins implement `analyzeCommits`, the highest release type returned wins.
`verifyRelease`	Verify Release	No	Verify the parameters of the release that is about to be published, such as version, type, or distribution tag.
`generateNotes`	Generate Notes	No	Generate the content of the release note. If multiple plugins implement `generateNotes`, the release notes will be the concatenation of each plugin output.
`prepare`	Prepare	No	Prepare the release, for example by creating or updating files such as `package.json`, `CHANGELOG.md`, documentation, or compiled assets and pushing a commit.
`publish`	Publish	No	Publish the release.
`addChannel`	Add Channel (optional)	No	Assign the release to a distribution channel when channel management is needed, for example by adding an npm dist-tag.
`success`	Notify	No	Notify consumers or maintainers after a successful release.
`fail`	Notify	No	Notify consumers or maintainers after a failed release.

For each release step, semantic-release runs every plugin in the plugins array that implements the hook for that step.

Not every release step is hook-backed. For example, core handles Get Last Release and Create Git Tag directly. addChannel is a special-case hook used only when channel management applies.

Plugins installation

Default plugins

These four plugins are already part of semantic-release and are listed in order of execution. They should not be installed separately; installing them independently can result in conflicting behavior if multiple versions are present:

"@semantic-release/commit-analyzer"
"@semantic-release/release-notes-generator"
"@semantic-release/npm"
"@semantic-release/github"

Additional plugins

Additional plugins should be provided to npx with --package when running semantic-release:

$ npx \
  --package semantic-release \
  --package @semantic-release/git \
  --package @semantic-release/changelog \
  semantic-release

See the official and community plugins list for packages that extend semantic-release beyond the default set.

If you want to build your own plugin, see Plugin development.

Plugins declaration and execution order

If you need to customize the default plugin set or execution order, configure the plugins option by listing plugins by npm module name.

{
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/npm"
  ]
}

For each release step, the plugins that implement that step’s lifecycle hook will be executed in the order in which they are defined.

{
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/npm",
    "@semantic-release/git"
  ]
}

With this configuration semantic-release will:

execute the verifyConditions implementation of @semantic-release/npm then @semantic-release/git
execute the analyzeCommits implementation of @semantic-release/commit-analyzer
execute the generateNotes implementation of @semantic-release/release-notes-generator
execute the prepare implementation of @semantic-release/npm then @semantic-release/git
execute the publish implementation of @semantic-release/npm

Order is first determined by release steps (such as Verify Conditions → Analyze Commits). At each release step, plugins are executed in the order in which they are defined.

Plugin options configuration

A plugin configuration can be specified by wrapping the name and an options object in an array. Options configured this way will be passed only to that specific plugin.

Global plugin configuration can be defined at the root of the semantic-release configuration object. Options configured this way will be passed to all plugins.

{
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    [
      "@semantic-release/github",
      {
        "assets": ["dist/**"]
      }
    ],
    "@semantic-release/git"
  ],
  "preset": "angular"
}

With this configuration:

All plugins will receive the preset option, which will be used by both @semantic-release/commit-analyzer and @semantic-release/release-notes-generator (and ignored by @semantic-release/github and @semantic-release/git)
The @semantic-release/github plugin will receive the assets option (@semantic-release/git will not receive it and therefore will use its default value for that option)