Introduction

Depending on the repository, the process of setting up publishing to npm when creating a release on GitHub may differ. However, there is a common pattern you can rely on.

This guide is updated for the shared publish action hosted in the build-system repository:

https://github.com/DevExpress/testcafe-build-system/blob/main/actions/publish/action.yml

Preparing the Repository Codebase

1. Add a release workflow in .github/workflows/ (for example, on-release.yml) that runs when a release is published.

2. Configure a release workflow (on-release.yml) to call the shared action directly:

name: On-release

on:
  release:
    types: [published]

permissions:
  id-token: write
  contents: read

jobs:
  publish:
    if: ${{ !github.event.release.draft }}
    runs-on: ubuntu-latest
    environment: npmjs
    steps:
      - uses: actions/checkout@v6
        with:
          ref: ${{ github.event.release.target_commitish }}

      - uses: DevExpress/testcafe-build-system/actions/publish@main
        with:
          token: ${{ secrets.NPM_TOKEN }}
          version: ${{ github.event.release.tag_name }}
          branch: ${{ github.event.release.target_commitish }}
          pre-publish-script: npm test

Important: you do not need to copy a local publish.yml into each repository. The publish logic is centralized in the shared action and is referenced from on-release.yml.

The shared publish action is documented here:

https://github.com/DevExpress/testcafe-build-system/blob/main/actions/publish/action.yml

3. Use release tags in the format v<release_version> and keep package.json version as <release_version>.

   Example:

   • If package.json version is 1.2.3, release tag should be v1.2.3.
   • The shared publish action strips the leading v from the version input before checking package.json.
   • A plain value like 1.2.3 in version input is invalid and will fail.

4. Ensure your package can be published from CI (npm publish works with your package configuration and access level).

5. (Optional) Add additional inputs in the release workflow if needed:

with:
  pre-publish-script: npm test
  post-publish-script: npm run smoke
  publish-command: npm publish
  publish-tag: latest
  audit-level: critical
  branch: ${{ github.event.release.target_commitish }}
  version: ${{ github.event.release.tag_name }}

Publish Workflow Inputs

The shared publish action (DevExpress/testcafe-build-system/actions/publish) supports these inputs.

Reference:

https://github.com/DevExpress/testcafe-build-system/blob/main/actions/publish/action.yml

• version (required)

  • Version passed from release tag in v<release_version> format (for example v1.2.3).
  • Action normalizes this to 1.2.3 for package.json comparison.

• branch (optional, default: master)

  • Branch/ref used for checkout before validation/publish.
  • Recommended to always pass github.event.release.target_commitish from release workflows.
  • Important: if your repository default branch is main, do not rely on the default master value.

• pre-publish-script (optional)

  • Command executed before publish (for example npm test).

• post-publish-script (optional)

  • Command executed after successful publish.

• publish-command (optional, default: npm publish)

  • Base publish command; workflow appends --tag <publish-tag>.

• publish-tag (optional, default: latest)

  • npm dist-tag used during publishing.

• audit-level (optional, default: critical)

  • Passed to npm audit --omit=dev --audit-level=<value>.
  • Allowed values in current docs: low, moderate, high, critical.

What the Workflow Validates

Before publishing, the shared action validates:

1. A git tag exists on the checked-out commit.
2. The version input starts with v (for example v1.2.3).
3. The commit tag matches the provided version input exactly.
4. package.json version equals normalized input version (without leading v).
5. npm audit --omit=dev passes at configured audit-level.

If a step fails, check the GitHub Actions step summary first, then open logs for full command output.

Manual Run (workflow_dispatch)

You can run your repository workflow (for example, on-release.yml) from the Actions tab if it also supports workflow_dispatch.

Example inputs:

• version: v1.2.3
• branch: main (or your target release branch)
• pre-publish-script: npm test (optional)

Notes:

• version must start with v.
• The git tag on the selected commit must exactly match version.
• package.json version must match normalized version (v1.2.3 → 1.2.3).

Configuring Secrets

1. Go to Settings → Secrets and variables → Actions.
2. Ensure that NPM_TOKEN exists.

Trusted Publishing (OIDC)

This publish flow supports npm Trusted Publishing via GitHub OIDC.

Known repositories already using Trusted Publishing:

• testcafe
• gulp-qunit-harness
• qunit-harnes
• sauce-tunnel

To make OIDC publishing work for a package, it must be configured in npm. Contact Roman Reshetnikov about this.

Notes:

• The caller workflow (for example, on-release.yml) must include permissions: id-token: write, which is required for OIDC.
• npm CLI uses OIDC in trusted environments and can still authenticate with NPM_TOKEN when needed.

Conclusion

1. If all steps were completed correctly, create a new GitHub release in the repository.
2. Create release tags using v<release_version> (for example, v1.2.3).
3. Monitor the publishing workflow execution. If any validation or publish step fails, the package will not be published to npm.
4. If your default branch is not master, always pass branch explicitly in the release workflow to avoid publishing from the wrong ref.
5. If you need to republish after fixing an issue, delete both the incorrect release and its tag on GitHub, then create a new release and tag that points to the latest commit.
6. Both release deletion and tag deletion can be done from the GitHub Web UI.