GitHub action to version and document a plugin release to npm using semantic-release.

• Creates tag for current version.
• GitHub release for tag with release notes based on commit messages.
• Publishes release to npm.
• Release triggered through release-npm commit annotation or manual run.
• No additional commits made.
• No version required in package.json.
• No project dependencies necessary.
• npm provenance support.

Add steps to build and test before the release as usual.

name: release

# Run action on every commit to main, release only when requested through commit annotation.
on:
  push:
    branches: [main]

jobs:
  build-test-release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: npm install
      - run: npm run build
      - run: npm test
      - uses: tobua/release-npm-action@v3
        with:
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

To request the next commit to be released if the pipeline passes add a remark to the commit message. Check out this blog post detailing semantic versioning and including a tool to generate commit messages including a release annotation.

feat(component): implement swipe and dot functionality for Intro

release-npm

If a release-npm token is found in the body a release will be triggered. Patch, minor or major release type will be decided based on the commit history.

fix(component): improve swipe behavior [release-npm]

The annotation can be placed anywhere in the commit message.

Alternatively, a release can be manually triggered without annotated commits. This requires the action to run on the workflow_dispatch trigger. When that is added a workflow can be triggered from the GitHub workflow UI for this action. The UI dialogue will prompt for an input which is set to 'regular' by default and when submitted with this value will trigger a manual release.

name: push

# Runs always on commits, will only release when requested, see below.
on:
  push:
    branches: [main]
  workflow_dispatch:
    inputs:
      manual:
        description: Manually trigger regular release?
        default: regular
        required: true

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      # ...
      - uses: tobua/release-npm-action@v3
        with:
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
          # Hand over manual input trigger.
          MANUAL_TRIGGER: ${{ github.event.inputs.manual }}

The following options can be passed to the action.

version, channel and tag are available as output variables after a successful release.

In order to publish your package with the contents signed have been built on GitHub in the linked repository add the following npm publishConfig to the package.json.

{
  "publishConfig": {
    "provenance": true
  }
}

jobs:
  release:
    runs-on: ubuntu-latest
    permissions:
      id-token: write # Required to mint token for npm package provenance
      contents: write # Needed to create and write release notes in GitHub release
    steps:
      - uses: actions/checkout@v3
      # ... install, built, test etc.
      - uses: tobua/release-npm-action@v3
        with:
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

• Node.js > 18 and npm > 9.5 (GitHub Action default)
• Provenance enabled in publishConfig, .npmrc or with npm publish --provenance flag
• Package already exists - will not work on first publish!
• id-token and contents permissions (minting token and publishing GitHub release in repository)
• Repository must be public

The first version for a plugin release defaults to 1.0.0 and cannot be changed. The next version is based on the commit history since the latest release and also cannot be changed.

Workaround To publish the first release below create an empty tag with a version below the one desired. So, to start publishing at 0.1.0 create a v0.0.1 tag on an earlier commit after which there are commits with feature which bumps the minor.

There are no relevant changes, so no new version is released. This happens if the commits since the last release don't contain any changes that would make it into the release. Note that commits with ci type don't need a release as by convention this only touches CI files which aren't published.

If you run into any issues with the action the likely cause is with semantic-release. You can try it out locally by running npx semantic-release --branches main --dry-run --no-ci without publishing anything.