fix npm publish bootstrap auth

Author: plutoless

.github/workflows/release.yml

@@ -258,24 +258,33 @@ jobs:
           ' packaging/npm/agoraio-cli/package.json > "$tmp"
           mv "$tmp" packaging/npm/agoraio-cli/package.json
 
-      - name: Prepare npm for trusted publishing
+      - name: Prepare npm publish auth
         if: steps.mode.outputs.mode == 'publish'
         shell: bash
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
         run: |
           set -euo pipefail
           # Trusted publishing requires npm CLI 11.5.1+.
           npm install -g npm@latest
           npm --version
           # setup-node writes an empty _authToken placeholder when registry-url is set
-          # without NODE_AUTH_TOKEN; remove it so npm uses OIDC trusted publishing.
-          if [ -n "${NPM_CONFIG_USERCONFIG:-}" ] && [ -f "$NPM_CONFIG_USERCONFIG" ]; then
+          # without NODE_AUTH_TOKEN; remove it in OIDC mode so npm uses trusted
+          # publishing. When NPM_TOKEN is configured, keep the placeholder so
+          # first-time package bootstraps can authenticate with the token.
+          if [ -n "${NODE_AUTH_TOKEN:-}" ]; then
+            echo "Using NPM_TOKEN for npm publish authentication."
+            npm whoami >/dev/null
+          elif [ -n "${NPM_CONFIG_USERCONFIG:-}" ] && [ -f "$NPM_CONFIG_USERCONFIG" ]; then
+            echo "Using npm trusted publishing for npm publish authentication."
             sed -i '/^\/\/registry\.npmjs\.org\/:_authToken=/d' "$NPM_CONFIG_USERCONFIG"
           fi
 
       - name: Publish platform packages
         shell: bash
         env:
           PUBLISH_ARGS: ${{ steps.mode.outputs.publish_args }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
         run: |
           set -euo pipefail
           for pkg in \
@@ -305,6 +314,7 @@ jobs:
         shell: bash
         env:
           PUBLISH_ARGS: ${{ steps.mode.outputs.publish_args }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
         run: |
           set -euo pipefail
           pkg="packaging/npm/agoraio-cli"

AGENTS.md

@@ -258,7 +258,8 @@ packaging/npm/
 6. Smoke-tests the published wrapper with `npx --yes agoraio-cli@<tag> --version` (retry/backoff for registry propagation)
 
 **Prerequisites:**
-- npm **Trusted Publisher** configured on each package (`agoraio-cli` and all `agoraio-cli-*`), pointing at repo `AgoraIO/cli` and workflow `release.yml`.
+- npm package names already exist on the registry before relying on trusted publishing. For first-time package creation, use a short-lived granular `NPM_TOKEN` repository secret for the bootstrap release, then remove it after trusted publishers are configured.
+- npm **Trusted Publisher** configured on each existing package (`agoraio-cli` and all `agoraio-cli-*`), pointing at repo `AgoraIO/cli` and workflow `release.yml`.
 - `id-token: write` workflow permission (already set in `release.yml`) — required for trusted publishing and provenance.
 
 **Manual dry-run:** the workflow exposes `workflow_dispatch` with a `dry_run` input that runs `npm publish --dry-run` against a synthetic version, validating packaging without publishing.

CHANGELOG.md

@@ -17,6 +17,7 @@ Earlier entries pre-date this convention and only carry their version's compare
 
 ### Fixed
 
+- Allow the npm release job to use a short-lived `NPM_TOKEN` bootstrap secret when platform packages do not yet exist on npm, while keeping trusted publishing as the default tokenless path.
 - Update GoReleaser Cosign signing to emit `checksums.txt.sigstore.json` with `--bundle`, matching Cosign's current bundle-based signing flow.
 
 ## [0.2.2] - 2026-05-26

RELEASING.md

@@ -25,7 +25,8 @@ The release workflow (`.github/workflows/release.yml`) then:
    - Publishes the six per-platform packages with `npm publish --provenance`
    - Publishes the wrapper package (`agoraio-cli`) with `npm publish --provenance`
    - Runs a post-publish smoke test: `npx --yes agoraio-cli@<tag> --version` with retry/backoff to handle registry propagation
-   - Authenticates via [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/) (OIDC from GitHub Actions — no `NPM_TOKEN` secret)
+   - Authenticates via [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/) (OIDC from GitHub Actions) once packages exist and trust is configured
+   - Can use `NPM_TOKEN` as a bootstrap fallback for first-time package publishes before trusted publishers can be configured
    - Requires `id-token: write` workflow permission (already set in `release.yml`)
 
 3. **Apt repository** job (triggered by the published release):
@@ -63,7 +64,8 @@ The release workflow exposes a `workflow_dispatch` trigger that runs the npm pub
 
 Before tagging the first real release that ships npm, confirm:
 
-- [ ] Each npm package has a **Trusted Publisher** configured on [npmjs.com](https://www.npmjs.com) (Package → Settings → Trusted Publisher → GitHub Actions):
+- [ ] Each npm package already exists on npm. If a package does not exist yet, add a short-lived granular `NPM_TOKEN` repository secret with publish rights for the bootstrap release, then remove it after configuring trusted publishing.
+- [ ] Each existing npm package has a **Trusted Publisher** configured on [npmjs.com](https://www.npmjs.com) (Package → Settings → Trusted Publisher → GitHub Actions):
   - Repository: `AgoraIO/cli`
   - Workflow filename: `release.yml`
   - Configure for `agoraio-cli` and all six `agoraio-cli-{os}-{arch}` platform packages
@@ -78,6 +80,7 @@ Before tagging the first real release that ships npm, confirm:
 | -------------------- | -------- | ------------------------------- |
 | `APT_SIGNING_KEY`    | secret   | Signed apt repo on GitHub Pages |
 | `APT_SIGNING_KEY_ID` | variable | Signed apt repo on GitHub Pages |
+| `NPM_TOKEN`          | secret   | Bootstrap npm publish only, before trusted publishers are configured |
 
 Homebrew and Scoop are not part of the current GoReleaser config. Add `brews:` / `scoops:` blocks before documenting them as automated channels.