ci: publish to npm when Release Please ships a GitHub Release (#639)

* ci: publish to npm when Release Please ships a GitHub Release

Run npm test then npm publish on release: published, checkout the release
tag, and document NPM_TOKEN plus manual fallback in CONTRIBUTING.md.

Co-authored-by: Cursor <cursoragent@cursor.com>

* ci: use RELEASE_PLEASE_TOKEN so publish workflow is triggered

GitHub does not start downstream workflows from events created with
GITHUB_TOKEN; Release Please needs a PAT for npm-publish to run.

Co-authored-by: Cursor <cursoragent@cursor.com>

* ci: keep GITHUB_TOKEN for Release Please

Drop RELEASE_PLEASE_TOKEN requirement; document manual npm publish when
the default token does not trigger downstream workflows.

Co-authored-by: Cursor <cursoragent@cursor.com>

---------

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: jimmyandrade

.github/workflows/npm-publish.yml

@@ -3,16 +3,37 @@ name: npm publish
 # Runs when Release Please creates a GitHub Release (see release-please.yml and ADR 0004).
 on:
   release:
-    types: [created]
+    types: [published]
 
 jobs:
   build:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
+        with:
+          ref: ${{ github.event.release.tag_name }}
       - uses: actions/setup-node@v6
         with:
           node-version: 24.x
           cache: npm
       - run: npm ci
       - run: npm test
+
+  publish-npm:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ github.event.release.tag_name }}
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24.x
+          registry-url: https://registry.npmjs.org/
+          cache: npm
+      - run: npm ci
+      - run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

CONTRIBUTING.md

@@ -156,11 +156,29 @@ Versioning is automated with [Release Please](https://github.com/googleapis/rele
 
 1. Merge changes to `master` using [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `docs:`, `ci:`, etc.).
 2. Release Please opens or updates a **Release PR** with the next version, `CHANGELOG.md`, and `package.json` updates.
-3. Review and merge the Release PR to create the git tag and GitHub Release.
-4. The `npm-publish` workflow runs when a GitHub Release is created.
+3. Review and merge the Release PR to create the git tag and GitHub Release on GitHub.
+4. Publish to npm (see **npm publishing** below). The [`npm-publish`](.github/workflows/npm-publish.yml) workflow listens for `release: published`, but releases created with the default `GITHUB_TOKEN` usually **do not** trigger downstream workflows — use manual publish or re-run the workflow from the Actions tab if needed.
 
 Do not run local `npm version` or push version tags manually unless coordinating an emergency release with maintainers.
 
+#### npm publishing
+
+Configure this repository secret under **Settings → Secrets and variables → Actions**:
+
+- **`NPM_TOKEN`** — npm access token with publish permission for the `webfont` package (Automation or Granular Access Token).
+
+After merging the Release PR, publish from the release tag (recommended):
+
+```shell
+git fetch origin --tags
+git checkout v12.0.0   # use the tag created by Release Please
+npm ci
+npm test
+npm publish --access public
+```
+
+Automated publishing does **not** retroactively upload versions that already exist as git tags only (for example `11.5.x` never published to npm).
+
 ## Resources
 
 - [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/)

docs/adr/0004-release-please-instead-of-standard-version.md

@@ -82,12 +82,12 @@ The project already uses [Conventional Commits](https://www.conventionalcommits.
 ### Negative / trade-offs
 
 - **Release PR cadence:** Version bumps no longer land instantly on every `master` push; they accumulate in a Release PR until merged.
-- **`GITHUB_TOKEN` limitation:** Releases and Release PRs created by the default token do not trigger other workflows that listen to `pull_request` from those events. If CI must run on Release PRs with full permissions, configure a PAT secret (see [Release Please Action docs](https://github.com/googleapis/release-please-action#github-credentials)).
+- **`GITHUB_TOKEN` limitation:** Releases created with the default token do **not** trigger other workflows (including `npm-publish.yml`). Publish manually from the release tag, or configure a PAT for Release Please later if fully automated publish is required (see [Release Please Action docs](https://github.com/googleapis/release-please-action#github-credentials)).
 - **Prereleases:** The old `npm run release-alpha` script is removed; use Conventional Commit prerelease notation or Release Please `release-as` / manifest options when needed.
 
 ### Follow-up
 
-- If npm registry publish should run automatically, extend `npm-publish.yml` with `npm publish` and `NPM_TOKEN` (today it only runs `npm test` on `release: created`).
+- ~~If npm registry publish should run automatically, extend `npm-publish.yml` with `npm publish` and `NPM_TOKEN` (today it only runs `npm test` on `release: created`).~~ Done in PR [#639](https://github.com/itgalaxy/webfont/pull/639): publish on `release: published` with `NPM_TOKEN`.
 
 ## References