GitHub Action: Publish

Overview

Publish a CI-produced Node.js package tarball to an npm-compatible registry

Usage

- uses: hoverkraft-tech/ci-github-nodejs/actions/publish@df348077afa4e79725151d50606e9dc63f86dcb6 # 0.24.4
  with:
    # Artifact ID of one package tarball uploaded by the package action
    # This input is required.
    package-tarball-artifact-id: ""

    # Registry URL used by npm publish
    # Default: `https://registry.npmjs.org`
    registry-url: https://registry.npmjs.org

    # Package access: public, restricted, or empty to use npm defaults
    # Default: `public`
    access: public

    # npm distribution tag, such as latest, next, or canary; empty uses npm defaults
    tag: ""

    # Whether to request provenance for npmjs.org publishes (true or false)
    # Default: `true`
    provenance: "true"

    # Validate publishing without uploading the package (true or false)
    # Default: `false`
    dry-run: "false"

    # GitHub token for downloading the artifact; registry authentication uses NODE_AUTH_TOKEN or OIDC
    # Default: `${{ github.token }}`
    github-token: ${{ github.token }}

Inputs

Input	Description	Required	Default
`package-tarball-artifact-id`	Artifact ID of one package tarball uploaded by the package action	true	-
`registry-url`	Registry URL used by npm publish	false	`https://registry.npmjs.org`
`access`	Package access: public, restricted, or empty to use npm defaults	false	`public`
`tag`	npm distribution tag, such as latest, next, or canary; empty uses npm defaults	false	-
`provenance`	Whether to request provenance for npmjs.org publishes (true or false)	false	`true`
`dry-run`	Validate publishing without uploading the package (true or false)	false	`false`
`github-token`	GitHub token for downloading the artifact; registry authentication uses NODE_AUTH_TOKEN or OIDC	false	`${{ github.token }}`

Examples

Authentication

npm trusted publishing

Configure an npm trusted publisher for your repository and the caller workflow filename.

Use a GitHub-hosted runner and grant the publishing job id-token: write.

The action uses the current Node.js LTS runtime; trusted publishing requires Node.js 22.14.0 or newer and npm 11.5.1 or newer.

No npm token is needed. The npm package must already exist before configuring its trusted publisher.

For public packages, ensure package.json has a repository.url matching the GitHub repository for provenance.

Registry tokens and GitHub Packages

Provide registry credentials as NODE_AUTH_TOKEN on the action step.

For npm token authentication, use an npm publishing token stored in a repository or environment secret.

For GitHub Packages, use a scoped package name, set the registry URL, and grant the job packages: write:

- uses: hoverkraft-tech/ci-github-nodejs/actions/publish@df348077afa4e79725151d50606e9dc63f86dcb6 # 0.24.4
  with:
    package-tarball-artifact-id: ${{ needs.package.outputs.package-tarball-artifact-id }}
    registry-url: https://npm.pkg.github.com
    provenance: "false"
  env:
    NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

The github-token input only authenticates artifact downloads; it is not an npm publishing credential.

Dry runs and prereleases

A dry run downloads the same tarball and executes npm publish --dry-run without publishing:

- uses: hoverkraft-tech/ci-github-nodejs/actions/publish@df348077afa4e79725151d50606e9dc63f86dcb6 # 0.24.4
  with:
    package-tarball-artifact-id: ${{ needs.package.outputs.package-tarball-artifact-id }}
    dry-run: "true"
    provenance: "false"
    tag: next

Dry runs do not verify registry authorization or reserve the package version.

Use tag: next for a prerelease tarball such as 1.2.0-rc.1; the distribution tag does not change the version inside it.

Publish only after the checks for that exact artifact succeed. Re-running a successful publish for the same package version fails because npm versions are immutable.