plugins.md

Plugins

Each release step is implemented within a plugin or a list of plugins that can be configured. This allows for support of different commit message formats, release note generators and publishing platforms.

See plugins list.

Plugin types

verifyConditions plugin

Responsible for verifying conditions necessary to proceed with the release: configuration is correct, authentication token are valid, etc...

Default implementation: @semantic-release/npm and @semantic-release/github.

analyzeCommits plugin

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

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

verifyRelease 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 is able to verify that if a release contains breaking changes, its type must be major.

Default implementation: none.

generateNotes plugin

Responsible for generating release notes.

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

prepare 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: @semantic-release/npm.

publish plugin

Responsible for publishing the release.

Default implementation: @semantic-release/npm and @semantic-release/github.

success plugin

Responsible for notifying of a new release.

Default implementation: @semantic-release/github.

fail plugin

Responsible for notifying of a failed release.

Default implementation: @semantic-release/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 with the other semantic-release options will apply to all plugins. Options defined within the plugin Object will apply to that 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