Custom Shell Commands with @semantic-release/exec

Running Custom Commands During Release

The @semantic-release/exec plugin lets you execute arbitrary shell commands at each step of the semantic-release lifecycle. This is the most flexible plugin for integrating with custom build systems, deployment tools, or notification services.

Configuration

{
  "branches": ["main"],
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    ["@semantic-release/exec", {
      "verifyConditionsCmd": "test -f Dockerfile",
      "prepareCmd": "npm run build && echo ${nextRelease.version} > VERSION",
      "publishCmd": "./scripts/deploy.sh ${nextRelease.version}",
      "successCmd": "curl -X POST https://hooks.slack.com/services/xxx -d '{"text": "Released v${nextRelease.version}"}'",
      "failCmd": "curl -X POST https://hooks.slack.com/services/xxx -d '{"text": "Release failed!"}'"
    }],
    "@semantic-release/github"
  ]
}

Lifecycle Hooks

Each command runs at a specific point in the release process:

Hook	When It Runs
verifyConditionsCmd	Before anything else — validates prerequisites
analyzeCommitsCmd	During commit analysis
verifyReleaseCmd	After release type is determined
generateNotesCmd	During release notes generation
prepareCmd	Before publishing — build, bundle, etc.
publishCmd	The actual publish step
successCmd	After successful release
failCmd	If the release fails

Template Variables in Commands

All commands have access to environment variables:

• ${nextRelease.version} — the new version (e.g., 1.2.3)
• ${nextRelease.type} — major, minor, or patch
• ${nextRelease.channel} — the release channel
• ${lastRelease.version} — the previous version

Multiple Exec Plugins

You can include multiple instances of the exec plugin if different commands need to run at different stages with different failure handling.