chore(ci): restore

Author: mandarini

.github/workflows/publish.yml

@@ -16,7 +16,7 @@ env:
   NODE_VERSION: '20'
 
 jobs:
-  release-stable:
+  release-stable: # stable releases can only be manually triggered
     if: ${{ github.event_name == 'workflow_dispatch' }}
     runs-on: ubuntu-latest
     permissions:
@@ -74,6 +74,7 @@ jobs:
           cache: 'npm'
           registry-url: 'https://registry.npmjs.org'
 
+      # Ensure npm 11.5.1 or later is installed for trusted publishing support
       - name: Update npm
         run: npm install -g npm@latest
 
@@ -206,7 +207,12 @@ jobs:
     uses: ./.github/workflows/ci-auth-js-node18.yml
     permissions:
       actions: read
-      contents: read
+      contents:
+        read
+
+  # ==========================================
+  # CANARY RELEASE (only on master, after all CI passes)
+  # ==========================================
 
   release-canary:
     name: Release Canary
@@ -215,6 +221,7 @@ jobs:
     permissions:
       contents: read
       id-token: write
+    # Only run on master branch pushes, and only if all CI jobs succeeded
     if: |
       github.ref == 'refs/heads/master' &&
       github.event_name == 'push' &&
@@ -241,6 +248,7 @@ jobs:
           cache: 'npm'
           registry-url: 'https://registry.npmjs.org'
 
+      # Ensure npm 11.5.1 or later is installed for trusted publishing support
       - name: Update npm
         run: npm install -g npm@latest
       - name: Install dependencies

scripts/release-stable.ts

@@ -69,6 +69,12 @@ function safeExec(cmd: string, opts = {}) {
 
   // --- GIT AUTH SETUP FOR TAGGING/CHANGELOG ---
 
+  // releaseChangelog should use the GitHub token with permission for tagging
+  // before switching the token, backup the GITHUB_TOKEN so that it
+  // can be restored afterwards and used by releasePublish. We can't use the same
+  // token, because releasePublish wants a token that has the id_token: write permission
+  // so that we can use OIDC for trusted publishing
+
   const gh_token_bak = process.env.GITHUB_TOKEN
   process.env.GITHUB_TOKEN = process.env.RELEASE_GITHUB_TOKEN
 
@@ -94,7 +100,8 @@ function safeExec(cmd: string, opts = {}) {
   })
 
   // --- RESTORE GIT AUTH FOR PUBLISHING ---
-
+  // npm publish with OIDC
+  // not strictly necessary to restore the header but do it incase  we require it later
   if (originalAuth) {
     safeExec(`git config --local http.https://github.com/.extraheader "${originalAuth}"`)
   } else {