npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@cycjimmy/semantic-release-action

v8.1.4

Published

GitHub Action for Semantic Release

Readme

Semantic Release Action

Release date semantic-release npm license

GitHub Action for Semantic Release.

Usage

Step1: Set any Semantic Release Configuration in your repository.

Step2: Add Secrets in your repository for the Semantic Release Authentication Environment Variables.

Step3: Add a Workflow File to your repository to create custom automated processes.

Basic Usage:

steps:
  - name: Checkout
    uses: actions/checkout@v7
  - name: Semantic Release
    uses: cycjimmy/semantic-release-action@v8
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

IMPORTANT: GITHUB_TOKEN does not have the required permissions to operate on protected branches. If you are using this action for protected branches, replace GITHUB_TOKEN with Personal Access Token. If using the @semantic-release/git plugin for protected branches, avoid persisting credentials as part of actions/checkout@v7 by setting the parameter persist-credentials: false. This credential does not have the required permission to operate on protected branches.

Private Packages

If you are using this action to publish to the npm GitHub Packages Registry, then make sure that you configure this in your package.json file:

{
  "publishConfig": {
    "registry": "https://npm.pkg.github.com"
  }
}

Inputs

| Input Parameter | Required | Description | |:-----------------:|:--------:|--------------------------------------------------------------------------------------------------------------------------| | semantic_version | false | Specify version range for semantic-release (v20 or above required). [Details] | | branches | false | The branches on which releases should happen.[Details]Requires semantic-release v20 or above. | | extra_plugins | false | Extra plugins for pre-install. [Details] | | dry_run | false | Whether to run semantic release in dry-run mode. [Details] | | ci | false | Whether to run semantic release with CI support. [Details] | | unset_gha_env | false | Whether to unset the GITHUB_ACTIONS environment variable. | | extends | false | Use a sharable configuration [Details] | | working_directory | false | Use another working directory for semantic release [Details] | | tag_format | false | Specify format of tag (useful for monorepos) | | repository_url | false | The Git repository url. If no repository url specified, current repository will be used by default. | | skip_npm_plugin | false | Whether to skip the @semantic-release/npm default plugin. [Details]Useful for non-Node.js projects. |

semantic_version

{Optional Input Parameter} Specify version range for semantic-release.The minimum supported semantic-release version is v20; older versions fail with an error.

steps:
  - name: Checkout
    uses: actions/checkout@v7
  - name: Semantic Release
    uses: cycjimmy/semantic-release-action@v8
    with:
      semantic_version: 20.0.1  # It is recommended to specify a version range
                                # for semantic-release when using
                                # semantic-release-action lower than @v4
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

If no version range is specified with cycjimmy/semantic-release-action@v8 then semantic-release@latest is used.

branches

{Optional Input Parameter} The branches on which releases should happen.branches requires semantic-release v20 or above.

steps:
  - name: Checkout
    uses: actions/checkout@v7
  - name: Semantic Release
    uses: cycjimmy/semantic-release-action@v8
    with:
      semantic_version: 20
      # you can set branches for semantic-release v20 or above.
      branches: |
        [
          '+([0-9])?(.{+([0-9]),x}).x',
          'main',
          'next',
          'next-major',
          {
            name: 'beta',
            prerelease: true
          },
          {
            name: 'alpha',
            prerelease: true
          }
        ]
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

branches will override the branches attribute in your configuration file. If the attribute is not configured on either side, semantic-release uses its own defaults. For the bundled semantic-release v25.0.9, these are:

[
  '+([0-9])?(.{+([0-9]),x}).x',
  'master',
  'main',
  'next',
  'next-major',
  {name: 'beta', prerelease: true},
  {name: 'alpha', prerelease: true}
]

NOTE: semantic-release treats the first release branch that exists in your repository as the default one (published to the latest npm dist-tag and as the Latest GitHub Release), and every other release branch gets a distribution channel named after the branch. With the defaults above, if your repository still has a leftover master branch next to main, releases from main would be published to the main npm dist-tag instead of latest, and their GitHub Releases would be flagged as pre-releases. If your default branch is main, explicitly list it first (as in the example above) and remove stale master branches.

See configuration#branches for more information.

NOTE: The branches input is evaluated as a JavaScript expression to support the array/object configuration above. Only pass content you trust — anyone able to edit the workflow file can already run arbitrary commands in your CI.

extra_plugins

{Optional Input Parameter} Extra plugins for pre-install.

The action can be used with extra_plugins option to specify plugins which are not in the default list of plugins of semantic release. When using this option, please make sure that these plugins are also mentioned in your semantic release config's plugins array.

For example, if you want to use @semantic-release/git and @semantic-release/changelog extra plugins, these must be added to extra_plugins in your actions file and plugins in your release config file as shown bellow:

Github Action Workflow:

steps:
  - name: Checkout
    uses: actions/checkout@v7
  - name: Semantic Release
    uses: cycjimmy/semantic-release-action@v8
    with:
      # You can specify specifying version range for the extra plugins if you prefer.
      extra_plugins: |
        @semantic-release/[email protected]
        @semantic-release/git
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

Similar to parameter semantic_version. It is recommended to manually specify a version of semantic-release plugins to prevent errors caused.

NOTE: extra_plugins accepts npm package specs (e.g. @semantic-release/[email protected] or @semantic-release/git@>=10.0.0) separated by whitespace or newlines. Each spec is passed to npm install as a single argument without a shell; tokens starting with - or containing quotes or similar unsafe characters are ignored and reported as a warning. Because whitespace separates specs, version ranges containing spaces (e.g. >=1.0.0 <2.0.0) are not supported. The same rules apply to the extends input.

Release Config:

  plugins: [
    .
+   "@semantic-release/changelog"
+   "@semantic-release/git",
  ]

dry_run

{Optional Input Parameter} Whether to run semantic release in dry-run mode.It will override the dryRun attribute in your configuration file.

steps:
  - name: Checkout
    uses: actions/checkout@v7
  - name: Semantic Release
    uses: cycjimmy/semantic-release-action@v8
    with:
      dry_run: true
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

NOTE: dry-run mode still requires write access to the repository. At startup, semantic-release verifies push permission by running git push --dry-run (verifyAuth), and GitHub enforces write access for dry-run pushes as well — nothing is actually pushed. If the credentials cannot push — for example, the default GITHUB_TOKEN when the job does not grant permissions: contents: write — the action fails with EGITNOPERMISSION: Cannot push to the Git repository. even in dry-run mode. To fix it, grant write permission to the job, e.g. permissions: contents: write (or use a token with write access).

ci

{Optional Input Parameter} Whether to run semantic release with CI support (default true).

steps:
  - name: Checkout
    uses: actions/checkout@v7
  - name: Semantic Release
    uses: cycjimmy/semantic-release-action@v8
    with:
      ci: false
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

ci can be used, e.g in combination with dry_run when generating the next release version in pull requests, where semantic_release would normally block the execution.

extends

The action can be used with extends option to extend an existing sharable configuration of semantic-release. Can be used in combination with extra_plugins.

steps:
  - name: Checkout
    uses: actions/checkout@v7
  - name: Semantic Release
    uses: cycjimmy/semantic-release-action@v8
    with:
      # You can extend an existing shareable configuration.
      # And you can specify version range for the shareable configuration if you prefer.
      extends: |
        @semantic-release/apm-config@^9.0.0
        @mycompany/override-config
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

working_directory

This action run semantic release in the github provided workspace by default. You can override it by setting another working directory.

steps:
  - name: Checkout
    uses: actions/checkout@v7
  - name: Semantic Release
    uses: cycjimmy/semantic-release-action@v8
    with:
      # You can select another working directory like a subdirectory for example.
      working_directory: ./code
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

tag_format

The default tag format on semantic-release is v${version}. You can override that behavior using this option (helpful when you are using monorepos)

steps:
  - name: Checkout
    uses: actions/checkout@v7
  - name: Semantic Release
    uses: cycjimmy/semantic-release-action@v8
    with:
      tag_format: custom-v${version}
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

unset_gha_env

Setting this to true will unset the GITHUB_ACTIONS environment variable. This can be useful when wanting to validate things such as merging of a PR would create a valid release.

steps:
  - name: Checkout
    uses: actions/checkout@v7
  - name: Temporarily merge PR branch
    if: ${{ github.event_name == 'pull_request' }}
    run: |
      git config --global user.name github-actions
      git config --global user.email [email protected]
      git merge --no-ff origin/${{ github.event.pull_request.head.ref }} --message "${{ github.event.pull_request.title }}"
  - name: Semantic Release
    uses: cycjimmy/semantic-release-action@v8
    with:
      unset_gha_env: ${{ github.event_name == 'pull_request' }}
      ci: ${{ github.event_name == 'pull_request' && false || '' }}
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

skip_npm_plugin

{Optional Input Parameter} Whether to skip the @semantic-release/npm default plugin.Useful for running the action in a project that is not a Node.js project (i.e. without a package.json file).

steps:
  - name: Checkout
    uses: actions/checkout@v7
  - name: Semantic Release
    uses: cycjimmy/semantic-release-action@v8
    with:
      skip_npm_plugin: true
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

The @semantic-release/npm default plugin requires a package.json file in the working directory. Without one, semantic-release fails with SemanticReleaseError: Missing package.json file. (ENOPKG) — even in dry-run mode. Set skip_npm_plugin: true to remove the npm plugin from the default plugins. The default plugins are then replaced with the following list (the default plugins of semantic-release without @semantic-release/npm):

  • @semantic-release/commit-analyzer
  • @semantic-release/release-notes-generator
  • @semantic-release/github

Similar to the other options, it will override the plugins attribute in your configuration file. If you already maintain your own plugins array in your release configuration, you don't need this input — just omit @semantic-release/npm from your array.

NOTE: NPM_TOKEN is not required when the npm plugin is skipped. Also note that configuring npmPublish: false or private: true on the npm plugin does not avoid the ENOPKG error, as the plugin checks for a package.json file before taking those settings into account. The only way to release a project without a package.json file is to not use the npm plugin at all.

Debugging

This action runs semantic-release as a library, so the CLI --debug flag is not available. Instead, set the DEBUG environment variable — semantic-release's internal debug logs (semantic-release:config, semantic-release:plugins, semantic-release:git, etc.) are printed to stderr:

steps:
  - name: Checkout
    uses: actions/checkout@v7
  - name: Semantic Release
    uses: cycjimmy/semantic-release-action@v8
    with:
      dry_run: true
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      DEBUG: semantic-release:*

This is equivalent to running semantic-release --debug locally. You can also enable a single namespace to reduce noise, e.g. DEBUG: semantic-release:git.

Outputs

| Output Parameter | Description | |:-------------------------:|-----------------------------------------------------------------------------------------------------------------------------------| | new_release_published | Whether a new release was published. The return value is in the form of a string. ("true" or "false") | | new_release_version | Version of the new release. (e.g. "1.3.0") | | new_release_major_version | Major version of the new release. (e.g. "1") | | new_release_minor_version | Minor version of the new release. (e.g. "3") | | new_release_patch_version | Patch version of the new release. (e.g. "0") | | new_release_channel | The distribution channel on which the last release was initially made available (undefined for the default distribution channel). | | new_release_notes | The release notes for the new release. | | new_release_git_head | The sha of the last commit being part of the new release | | new_release_git_tag | The Git tag associated with the new release. | | last_release_version | Version of the previous release, if there was one. (e.g. 1.2.0) | | last_release_git_head | The sha of the last commit being part of the last release, if there was one. | | last_release_git_tag | The Git tag associated with the last release, if there was one. | |

NOTE: When no new release is published, semantic-release resolves to false and no release data is returned. In that case the last_release_* outputs are determined on a best-effort basis from the local Git tags: the highest stable version matching tag_format (the tag_format input, or the version is extracted from the tag name when the input is not set) is used, falling back to the highest pre-release version only when no stable version exists. Setups with several release channels or maintenance branches may resolve to a different last release than the one semantic-release would report.

Using Output Variables:

steps:
  - name: Checkout
    uses: actions/checkout@v7
  - name: Semantic Release
    uses: cycjimmy/semantic-release-action@v8
    id: semantic   # Need an `id` for output variables
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

  - name: Do something when a new release published
    if: steps.semantic.outputs.new_release_published == 'true'
    run: |
      echo ${{ steps.semantic.outputs.new_release_version }}
      echo ${{ steps.semantic.outputs.new_release_major_version }}
      echo ${{ steps.semantic.outputs.new_release_minor_version }}
      echo ${{ steps.semantic.outputs.new_release_patch_version }}

Migration Notes

The branch input has been removed

The branch input is no longer supported. Use the branches input instead:

  - name: Semantic Release
    uses: cycjimmy/semantic-release-action@v8
    with:
-     branch: your-branch
+     branches: your-branch

If the branch input is still passed, the action prints a deprecation warning and ignores it.

semantic-release below v20 is no longer supported

This action now requires semantic-release v20 or above. If the installed semantic-release version is older (for example via semantic_version: 19), the action fails with an error. Update the semantic_version input to v20 or above, or remove it to use the latest version.

Changelog

See CHANGELOG.

License

This project is released under the MIT License.