Release
The Release Node.js workflow publishes your package to npm and finishes the GitHub release, starting from a version tag you create on your machine. This page is for maintainers of a Node.js project created from Scaffold. It covers the one-time npm setup, releasing a version, what the workflow does and how anyone can verify a downloaded script.
Release only by pushing a version tag. Never click Publish release on the draft release: a published release makes the workflow stop, so the release never gets its assets.
Before you begin
The workflow publishes to npm through trusted publishing, so your repository stores no npm token. npm trusts the workflow from settings on the package's page, so the package has to exist on npm first.
To set up npm publishing:
-
Check that
repositoryinpackage.jsonpoints to your GitHub repository. npm compares it with the repository that runs the workflow. -
From your machine, publish the first version:
npm publish --access public -
On npmjs.com, open the package's Settings and add a trusted publisher for GitHub Actions. Enter your repository's owner and name, and
release-nodejs.ymlas the workflow filename.
To release on GitHub only, set "private": true in package.json. The workflow then skips npm and still finishes the GitHub release.
Release a version
With Release Drafter, a draft release holds the notes for every pull request merged into main. The draft's version is Release Drafter's guess, and the tag you push replaces it. Without a draft, the workflow creates a release with generated notes.
To release a version:
-
Optional: Open the draft release on your repository's Releases page. Edit its notes if they need it.
-
On an up-to-date
mainwith no uncommitted changes, set the version:npm version 1.2.3npm versionsets the version inpackage.json, commits the change asReleased 1.2.3.and tags the commit1.2.3. The project's.npmrcmakes the tag the bare version, with nov. -
Push the commit and the tag:
git push origin main --follow-tags -
On the Actions tab, open the
Release Node.jsrun for the tag. Confirm that it passes. -
Confirm that the release is published with
nodejs-script,REPO-nodejs-TAG.sha256andREPO-nodejs-TAG.intoto.jsonl. Confirm that npm lists the version.
A version with a suffix, such as 1.2.3-rc.1, goes to npm under the next dist-tag and becomes a GitHub pre-release.
What the workflow does
The workflow runs 2 jobs. It starts only on a version tag on the default branch, as the release checks describe.
The Build Node.js release job has read-only access to the repository contents. It runs these steps:
- Checks that the tag equals the version in
package.json. - Packs the npm package with
npm pack. Thefileslist inpackage.jsonlimits the package tonodejs-script. - Writes the SHA-256 checksum of
nodejs-scripttoREPO-nodejs-TAG.sha256, whereREPOis the repository name andTAGis the tag name. - Signs a build provenance attestation for the package, the script and the checksum file, and saves the attestation bundle as
REPO-nodejs-TAG.intoto.jsonl. - Checks the checksum and the attestation.
On a private repository, the job skips the attestation and the bundle, because GitHub offers attestations for private repositories only on GitHub Enterprise Cloud.
The Publish Node.js release job has write access to the repository contents. It runs these steps:
- Publishes the package to npm with provenance. It skips npm when the version is already there, so a rerun doesn't fail.
- Waits for any running
Draft release notesrun, because that run sets the draft's tag back to its own guess. - Renames the draft to the tag and fixes the version in its compare link. Without a draft, it creates a release with generated notes.
- Attaches
nodejs-scriptand both files, then publishes the release.
A release becomes the latest GitHub release only when no published release has a higher version. Push 1 version tag at a time. GitHub starts no workflow for a push that holds more than 3 tags. Release runs for different tags publish 1 at a time. When 2 or more runs wait behind a running release, GitHub cancels every waiting run except the newest, so re-run each canceled release from the Actions tab.
Verify a release
Anyone who downloads nodejs-script can confirm that your repository's release workflow built it. To verify the script:
-
From the release page, download
nodejs-scriptandREPO-nodejs-TAG.sha256. -
Check the checksum:
sha256sum --check REPO-nodejs-TAG.sha256On macOS, run
shasum -a 256 --check REPO-nodejs-TAG.sha256instead. -
Check the attestation with GitHub CLI:
gh attestation verify nodejs-script --repo OWNER/REPO
Replace OWNER/REPO with the repository and TAG with the release's tag. To check the attestation without reading it from GitHub, download REPO-nodejs-TAG.intoto.jsonl too and add --bundle REPO-nodejs-TAG.intoto.jsonl to the gh attestation verify command. For the npm package, run npm audit signatures in a project that installs it.