@semantic-release/exec

What is @semantic-release/exec?

@semantic-release/exec is a plugin for semantic-release that allows you to execute shell commands at different points in the release lifecycle. This can be useful for tasks such as running custom scripts, updating documentation, or performing other actions that are not covered by the default plugins.

What are @semantic-release/exec's main functionalities?

Prepare Command

The prepare command is executed during the prepare step of the release process. This can be used to run any custom scripts or commands needed to prepare the release.

{"plugins":["@semantic-release/exec",{"prepareCmd":"echo 'Preparing release version ${nextRelease.version}'"}]}

Publish Command

The publish command is executed during the publish step of the release process. This can be used to run any custom scripts or commands needed to publish the release.

{"plugins":["@semantic-release/exec",{"publishCmd":"echo 'Publishing release version ${nextRelease.version}'"}]}

Success Command

The success command is executed after the release has been successfully published. This can be used to run any custom scripts or commands needed to finalize the release.

{"plugins":["@semantic-release/exec",{"successCmd":"echo 'Release version ${nextRelease.version} was successful'"}]}

Fail Command

The fail command is executed if the release process fails. This can be used to run any custom scripts or commands needed to handle the failure.

{"plugins":["@semantic-release/exec",{"failCmd":"echo 'Release version ${nextRelease.version} failed'"}]}

Other packages similar to @semantic-release/exec

shelljs

ShellJS is a portable (Windows/Linux/macOS) implementation of Unix shell commands on Node.js. It provides a way to execute shell commands within Node.js scripts, similar to @semantic-release/exec, but is more general-purpose and not specifically tied to the release lifecycle.

execa

Execa is a modern process execution library for Node.js. It provides a better interface for executing shell commands and handling their output compared to the built-in child_process module. While it can be used to achieve similar functionality as @semantic-release/exec, it is not specifically designed for the release lifecycle.

node-cmd

Node-cmd is a simple command-line/terminal interface for Node.js. It allows you to run shell commands from within your Node.js application. Like shelljs and execa, it is a general-purpose tool and not specifically designed for the release lifecycle.

README

@semantic-release/exec

semantic-release plugin to execute custom shell commands.

Step	Description
verifyConditions	Execute a shell command to verify if the release should happen.
analyzeCommits	Execute a shell command to determine the type of release.
verifyRelease	Execute a shell command to verifying a release that was determined before and is about to be published.
generateNotes	Execute a shell command to generate the release note.
prepare	Execute a shell command to prepare the release.
publish	Execute a shell command to publish the release.
success	Execute a shell command to notify of a new release.
fail	Execute a shell command to notify of a failed release.

Install

$ npm install @semantic-release/exec -D

Usage

The plugin can be configured in the semantic-release configuration file:

{
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    ["@semantic-release/exec", {
      "verifyConditionsCmd": "./verify.sh",
      "publishCmd": "./publish.sh ${nextRelease.version} ${options.branch} ${commits.length} ${Date.now()}"
    }],
  ]
}

With this example:

• the shell command ./verify.sh will be executed on the verify conditions step
• the shell command ./publish.sh 1.0.0 master 3 870668040000 (for the release of version 1.0.0 from branch master with 3 commits on August 4th, 1997 at 2:14 AM) will be executed on the publish step

Note: it's required to define a plugin for the analyze commits step. If no analyzeCommitsCmd is defined the plugin @semantic-release/commit-analyzer must be defined in the plugins list.

Configuration

Options

Options	Description
verifyConditionsCmd	The shell command to execute during the verify condition step. See verifyConditionsCmd.
analyzeCommitsCmd	The shell command to execute during the analyze commits step. See analyzeCommitsCmd.
verifyReleaseCmd	The shell command to execute during the verify release step. See verifyReleaseCmd.
generateNotesCmd	The shell command to execute during the generate notes step. See generateNotesCmd.
prepareCmd	The shell command to execute during the prepare step. See prepareCmd.
addChannelCmd	The shell command to execute during the add channel step. See addChannelCmd.
publishCmd	The shell command to execute during the publish step. See publishCmd.
successCmd	The shell command to execute during the success step. See successCmd.
failCmd	The shell command to execute during the fail step. See failCmd.
shell	The shell to use to run the command. See execa#shell.
execCwd	The path to use as current working directory when executing the shell commands. This path is relative to the path from which semantic-release is running. For example if semantic-release runs from /my-project and execCwd is set to buildScripts then the shell command will be executed from /my-project/buildScripts

Each shell command is generated with Lodash template. All the objects passed to the semantic-release plugins are available as template options.

verifyConditionsCmd

Execute a shell command to verify if the release should happen.

Command property	Description
exit code	0 if the verification is successful, or any other exit code otherwise.
stdout	Write only the reason for the verification to fail.
stderr	Can be used for logging.

analyzeCommitsCmd

Command property	Description
exit code	Any non 0 code is considered as an unexpected error and will stop the semantic-release execution with an error.
stdout	Only the release type (major, minor or patch etc..) can be written to stdout. If no release has to be done the command must not write to stdout.
stderr	Can be used for logging.

verifyReleaseCmd

Command property	Description
exit code	0 if the verification is successful, or any other exit code otherwise.
stdout	Only the reason for the verification to fail can be written to stdout.
stderr	Can be used for logging.

generateNotesCmd

Command property	Description
exit code	Any non 0 code is considered as an unexpected error and will stop the semantic-release execution with an error.
stdout	Only the release note must be written to stdout.
stderr	Can be used for logging.

prepareCmd

Command property	Description
exit code	Any non 0 code is considered as an unexpected error and will stop the semantic-release execution with an error.
stdout	Can be used for logging.
stderr	Can be used for logging.

addChannelCmd

Command property	Description
exit code	Any non 0 code is considered as an unexpected error and will stop the semantic-release execution with an error.
stdout	The release information can be written to stdout as parseable JSON (for example {"name": "Release name", "url": "http://url/release/1.0.0"}). If the command write non parseable JSON to stdout no release information will be returned.
stderr	Can be used for logging.

publishCmd

Command property	Description
exit code	Any non 0 code is considered as an unexpected error and will stop the semantic-release execution with an error.
stdout	The release information can be written to stdout as parseable JSON (for example {"name": "Release name", "url": "http://url/release/1.0.0"}). If the command write non parseable JSON to stdout no release information will be returned.
stderr	Can be used for logging.

successCmd

Command property	Description
exit code	Any non 0 code is considered as an unexpected error and will stop the semantic-release execution with an error.
stdout	Can be used for logging.
stderr	Can be used for logging.

failCmd

Command property	Description
exit code	Any non 0 code is considered as an unexpected error and will stop the semantic-release execution with an error.
stdout	Can be used for logging.
stderr	Can be used for logging.