Skip to content
Semantic Release Semantic Release Semantic Release

Running semantic-release

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

Section titled “Using npx (recommended)”

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

Terminal window
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:

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

Notes

Section titled “Notes”

  1. 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.

  2. 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.

  3. 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"
        }
      ]
    }

  4. 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.

Section titled “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