semantic-release/docs/usage/plugins.md

Plugins

Each release steps is implemented within a plugin or a list of plugins that can be configured, allowing to support different commit message format, release not generator and publishing platforms.

Plugin types

verifyConditions plugin

Plugin responsible for verifying all the conditions to proceed with the release: configuration is correct, authentication token are valid, etc...

Default implementation: npm and github.

analyzeCommits plugin

Plugin responsible for determining the type of the next release (major, minor or patch).

Default implementation: @semantic-release/commit-analyzer.

verifyRelease plugin

Plugin responsible for verifying the parameters (version, type, dist-tag etc...) of the release that is about to be published match certain expectations. For example the cracks plugin allows to verify that if a release contains breaking changes, its type must be major.

Default implementation: none.

generateNotes plugin

Plugin responsible for generating release notes.

Default implementation: @semantic-release/release-notes-generator.

prepare plugin

Plugin responsible for preparing the release, including:

• Creating or updating files such as package.json, CHANGELOG.md, documentation or compiled assets.
• Create and push commits

Default implementation: npm.

publish plugin

Plugin responsible for publishing the release.

Default implementation: npm and github.

success plugin

Plugin responsible for notifying of a new release.

Default implementation: github.

fail plugin

Plugin responsible for notifying of a failed release.

Default implementation: github.

Configuration

Plugin can be configured by specifying the plugin's module name or file path directly as a String or within the path key of an Object.

Plugins specific options can be set similarly to the other semantic-release options or within the plugin Object. Plugins options defined along the other semantic-release options will apply to all plugins, while the one defined within the plugin Object will apply only to this specific plugin.

For example:

{
  "release": {
    "verifyConditions": [
      {
        "path": "@semantic-release/exec",
        "cmd": "verify-conditions.sh"
      },
      "@semantic-release/npm",
      "@semantic-release/github"
    ],
    "analyzeCommits": "custom-plugin",
    "verifyRelease": [
      {
        "path": "@semantic-release/exec",
        "cmd": "verify-release.sh"
      },
    ],
    "generateNotes": "./build/my-plugin.js",
    "githubUrl": "https://my-ghe.com",
    "githubApiPathPrefix": "/api-prefix"
  }
}

With this configuration:

• the custom-plugin npm module will be used to analyze commits
• the ./build/my-plugin.js script will be used to generate release notes
• the @semantic-release/exec, @semantic-release/npm and @semantic-release/exec plugins will be used to verify conditions
• the @semantic-release/exec plugin will be used to verify the release
• the cmd option will be set to verify-conditions.sh only for the @semantic-release/exec plugin used to verify conditions
• the cmd option will be set to verify-release.sh only for the @semantic-release/exec plugin used to verify the release
• the githubUrl and githubApiPathPrefix options will be set to respectively https://my-ghe.com and /api-prefix for all plugins