Running semantic-release

How to run semantic-release in your CI pipeline using npx, including version pinning strategies and tradeoffs of local installation.

Using npx (recommended)

We recommend running semantic-release directly in the CI environment with npx:

npx semantic-release

If you need to leverage plugins and/or presets that are not included in the base semantic-release package, you can include them as part of your npx command as well:

npx --package semantic-release --package @semantic-release/exec --package conventional-changelog-conventionalcommits semantic-release

Notes

When running semantic-release with npx, we recommend setting at least the major version. For example, by using npx semantic-release@25. This way you control which major version of semantic-release is used by your pipeline, and thus avoid breaking the release when there’s a new major version of semantic-release. The same recommendation applies to any additional plugins and presets included in your npx command. Since plugins and presets, many of them developed by third-party projects, release new major versions on their own schedule, an unpinned plugin or preset can break your release just as unexpectedly. We recommend pinning all packages in your npx command:
Terminal window
```
npx --package semantic-release@25 --package conventional-changelog-conventionalcommits@9 semantic-release
```
Pinning semantic-release to an exact version makes your releases even more deterministic. But pinning also means you, or a bot, must upgrade semantic-release when a new version is released.

You can use Renovate’s regex manager to get automatic updates for semantic-release in either of the above scenarios. Put this in your Renovate configuration file:

{
  "customManagers": [
    {
      "customType": "regex",
      "description": "Update semantic-release version used by npx",
      "managerFilePatterns": ["^\\.github/workflows/[^/]+\\.ya?ml$"],
      "matchStrings": [
        "\\srun: npx semantic-release@(?<currentValue>.*?)\\s"
      ],
      "datasourceTemplate": "npm",
      "depNameTemplate": "semantic-release"
    }
  ]
}

npx is a tool bundled with npm@>=5.2.0. You can use it to download and run the semantic-release binary in a single step. See What is npx for more details.

Local installation (not recommended)

Since semantic-release isn’t truly a development dependency, but rather a release dependency, we recommend against installing it as a local dependency of your project. Instead, we recommend running it in your CI environment with npx as described above. Running only during the release process avoids:

installing unnecessary dependencies during development and testing, including the fairly sizable dependency on npm
installing a different version of npm into node_modules/ than the one used to run the release, which can lead to conflicts and unexpected behavior
installing dependencies that could conflict with other development dependencies, like commitlint