@codfish/actions 2.0.1 → 3.3.2

package/npm-publish-pr/README.md

@@ -1,13 +1,15 @@
 # npm-publish-pr
 
-Publishes packages with PR-specific version numbers for testing in downstream applications before merging. Automatically
-detects your package manager (npm, yarn, or pnpm) and uses the appropriate publish command. The action generates
-versions in the format `0.0.0-PR-{number}--{short-sha}` and automatically comments on the pull request with the
-published version.
+Publishes packages with PR-specific version numbers for testing in downstream applications before merging. Supports both
+**OIDC trusted publishing** (recommended) and token-based authentication. Automatically detects your package manager
+(npm, yarn, or pnpm) for token-based publishing. The action generates versions in the format
+`0.0.0-PR-{number}--{short-sha}` and automatically comments on the pull request with the published version.
 
 **Key Features:**
 
-- Automatic package manager detection (npm/yarn/pnpm)
+- **OIDC trusted publishing** support (no secrets required for public packages!)
+- Token-based authentication fallback for private packages
+- Automatic package manager detection (npm/yarn/pnpm) for token mode
 - Automatic PR version generation
 - Publishes to registry with `pr` tag
 - Automatic PR commenting with version info
@@ -15,75 +17,234 @@ published version.
 
 <!-- DOCTOC SKIP -->
 
+## Migrating to OIDC Trusted Publishing
+
+If you're currently using token-based authentication (`npm-token`), migrating to OIDC is recommended for public
+packages. OIDC provides better security, automatic provenance attestations, and eliminates the need to manage npm
+tokens.
+
+### Requirements
+
+1. **Public package** - OIDC trusted publishing only works with public repos & npm packages
+2. **npm 11.5.1+** - Required for OIDC support
+   - ✅ **Automatic**: Use `setup-node-and-install@v3` and it handles the npm upgrade for you
+   - 🔧 **Manual**: Run `npm install -g npm@^11.5.1` before publishing
+3. **Configure trusted publisher on npmjs.com** - One-time setup per package
+4. **Update workflow permissions** - Add `id-token: write` to your workflow
+
+### Migration Steps
+
+1. **Configure trusted publisher on npmjs.com:**
+   - Go to https://www.npmjs.com/package/YOUR-PACKAGE/access
+   - Click "Add trusted publisher"
+   - Fill in:
+     - Provider: `GitHub Actions`
+     - Organization/User: `your-github-username`
+     - Repository: `your-repo-name`
+     - Workflow: `<file>.yml` (exact filename, not the workflow `name`!)
+     - Environment: Leave blank (unless using GitHub environments)
+
+2. **Update your workflow:**
+
+   ```diff
+    on: pull_request_target
+
+    jobs:
+      publish:
+        runs-on: ubuntu-latest
+
+   +    permissions:
+   +      contents: read
+   +      id-token: write
+   +      pull-requests: write
+
+        steps:
+   +      # Use v3 for automatic npm 11.5.1+ upgrade
+   +      - uses: codfish/actions/setup-node-and-install@v3
+   +
+          - uses: codfish/actions/npm-pr-version@v3
+   -        with:
+   -          npm-token: ${{ secrets.NPM_TOKEN }}
+   ```
+
+3. **Test on a PR** - Create a test PR to verify OIDC publishing works
+
+4. **Remove npm token** - Once confirmed working, you can delete the `NPM_TOKEN` secret
+
 ## Usage
 
 See [action.yml](action.yml).
 
-```yaml
-steps:
-  - uses: actions/checkout@v5
+### OIDC Trusted Publishing (Recommended for Public Packages)
+
+No npm token required! Just configure your package on npmjs.com for trusted publishing.
+
+```yml
+on: pull_request
+
+jobs:
+  publish:
+    permissions:
+      id-token: write
+      pull-requests: write
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: codfish/actions/setup-node-and-install@v3
+        with:
+          node-version: lts/*
+
+      - run: npm run build
+
+      - uses: codfish/actions/npm-pr-version@v3
+```
+
+> **Note:** `setup-node-and-install@v3` automatically upgrades npm to v11 (required for OIDC).
+
+### Token-Based Authentication (For Private Packages)
+
+```yml
+on: pull_request
+
+jobs:
+  publish:
+    permissions:
+      pull-requests: write
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: codfish/actions/setup-node-and-install@v3
+        with:
+          node-version: lts/*
+
+      - run: npm run build
+
+      - uses: codfish/actions/npm-pr-version@v3
+        with:
+          npm-token: ${{ secrets.NPM_TOKEN }}
+```
 
-  - uses: codfish/actions/setup-node-and-install@v2
-    with:
-      node-version: lts/*
+### Tarball Mode (Secure for pull_request_target)
 
-  - run: npm run build
+For `pull_request_target` workflows, use tarball mode to prevent execution of malicious lifecycle scripts from untrusted
+PRs:
 
-  - uses: codfish/actions/npm-pr-version@v2
-    with:
-      npm-token: ${{ secrets.NPM_TOKEN }}
-      github-token: ${{ secrets.GITHUB_TOKEN }}
+```yml
+on: pull_request_target
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+
+      - uses: codfish/actions/setup-node-and-install@v3
+      - run: npm run build
+      - run: npm pack
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: package-tarball
+          path: '*.tgz'
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      pull-requests: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: package-tarball
+
+      - uses: codfish/actions/npm-pr-version@v3
+        with:
+          tarball: '*.tgz' # Publishes with --ignore-scripts
 ```
 
+> **Security:** Tarball mode automatically uses `--ignore-scripts` to prevent lifecycle script execution. See
+> [SECURITY.md](../SECURITY.md#npm-publishing-npm-pr-version) for complete security considerations.
+
 ### Disable PR Comments
 
-```yaml
-- uses: codfish/actions/npm-pr-version@v2
+```yml
+- uses: codfish/actions/npm-pr-version@v3
   with:
     npm-token: ${{ secrets.NPM_TOKEN }}
-    github-token: ${{ secrets.GITHUB_TOKEN }}
     comment: false
 ```
 
 ### Custom Comment Tag
 
-```yaml
-- uses: codfish/actions/npm-pr-version@v2
+```yml
+- uses: codfish/actions/npm-pr-version@v3
   with:
     npm-token: ${{ secrets.NPM_TOKEN }}
-    github-token: ${{ secrets.GITHUB_TOKEN }}
     comment-tag: my-custom-tag
 ```
 
 ## Complete Workflow Example
 
-```yaml
+### With OIDC (Recommended)
+
+```yml
 name: PR Package Testing
 
 on: pull_request_target
 
-permissions:
-  contents: write
-  pull-requests: write
+jobs:
+  publish-pr-package:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+      id-token: write
+      pull-requests: write
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: codfish/actions/setup-node-and-install@v3
+
+      - name: Build package
+        run: npm run build
+
+      - name: Publish PR package
+        uses: codfish/actions/npm-pr-version@v3
+```
+
+### With Token (Private Packages)
+
+```yml
+name: PR Package Testing
+
+on: pull_request_target
 
 jobs:
   publish-pr-package:
     runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+      pull-requests: write
+
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
 
-      - uses: codfish/actions/setup-node-and-install@v2
-        with:
-          node-version: 'lts/*'
+      - uses: codfish/actions/setup-node-and-install@v3
 
       - name: Build package
         run: npm run build
 
       - name: Publish PR package
-        uses: codfish/actions/npm-pr-version@v2
+        uses: codfish/actions/npm-pr-version@v3
         with:
           npm-token: ${{ secrets.NPM_TOKEN }}
-          github-token: ${{ secrets.GITHUB_TOKEN }}
 ```
 
 ## Testing Downstream
@@ -100,18 +261,31 @@ The package is published under the `pr` tag, so it won't interfere with your reg
 
 <!-- start inputs -->
 
-| Input          | Description                                                                         | Required | Default          |
-| -------------- | ----------------------------------------------------------------------------------- | -------- | ---------------- |
-| `npm-token`    | Registry authentication token with publish permissions (works with npm/yarn/pnpm)   | Yes      | -                |
-| `github-token` | GitHub token with pull request comment permissions (typically secrets.GITHUB_TOKEN) | Yes      | -                |
-| `comment`      | Whether to comment on the PR with the published version (true/false)                | No       | `true`           |
-| `comment-tag`  | Tag to use for PR comments (for comment identification and updates)                 | No       | `npm-publish-pr` |
+| Input         | Description                                                                                                                                                                                                                        | Required | Default          |
+| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ---------------- |
+| `npm-token`   | Registry authentication token with publish permissions. If not provided, OIDC trusted publishing will be used.                                                                                                                     | No       | -                |
+| `tarball`     | Path to pre-built tarball to publish (e.g., '\*.tgz'). When provided, publishes the tarball with --ignore-scripts for security. Recommended for pull_request_target workflows to prevent execution of malicious lifecycle scripts. | No       | -                |
+| `comment`     | Whether to comment on the PR with the published version (true/false)                                                                                                                                                               | No       | `true`           |
+| `comment-tag` | Tag to use for PR comments (for comment identification and updates)                                                                                                                                                                | No       | `npm-publish-pr` |
+| `dev`         | If true, use dev dependency install syntax in the PR comment (e.g. npm install -D, pnpm add -D).                                                                                                                                   | No       | `false`          |
 
 <!-- end inputs -->
 
-## Package Manager Support
+## Authentication Modes
+
+### OIDC Trusted Publishing (Recommended)
+
+When `npm-token` is not provided, the action uses OIDC trusted publishing:
 
-The action automatically detects your package manager and uses the appropriate publish command:
+- **Requires**: `id-token: write` permission in workflow
+- **Works with**: Public packages only
+- **Command**: Always uses `npm publish --access public --tag pr --provenance`
+- **Benefits**: No secrets required, automatic provenance attestations
+- **Setup**: Configure trusted publisher on npmjs.com (see [npm docs](https://docs.npmjs.com/trusted-publishers))
+
+### Token-Based Authentication
+
+When `npm-token` is provided, the action detects your package manager:
 
 - **npm**: Uses `npm publish --access public --tag pr`
 - **yarn**: Uses `yarn publish --access public --tag pr --new-version {version} --no-git-tag-version`
@@ -143,3 +317,109 @@ Examples:
 
 - `0.0.0-PR-123--abc1234` (PR #123, commit abc1234)
 - `0.0.0-PR-456--def5678` (PR #456, commit def5678)
+
+## Troubleshooting
+
+### Error: "Access token expired or revoked" / 404 Not Found
+
+This error typically occurs when using OIDC trusted publishing and indicates one of the following issues:
+
+#### Missing `id-token: write` Permission
+
+**Symptom:**
+
+```txt
+npm notice Access token expired or revoked. Please try logging in again.
+npm error code E404
+npm error 404 Not Found - PUT https://registry.npmjs.org/@your-package
+```
+
+**Solution:** Add `id-token: write` permission to your workflow:
+
+```yml
+permissions:
+  id-token: write # REQUIRED for OIDC!
+```
+
+Without this permission, GitHub cannot generate the OIDC token needed for npm trusted publishing.
+
+#### Workflow Name Mismatch
+
+**Symptom:** Same 404 error, but permissions are set correctly.
+
+**Solution:** Verify your npm trusted publisher configuration matches exactly:
+
+- Repository name is case-sensitive: `my-repo` ≠ `My-Repo`
+- Workflow filename must be exact: `validate.yml` not `.github/workflows/validate.yml` or `Validate Code`
+- Check at: https://www.npmjs.com/package/YOUR-PACKAGE/access
+
+#### Publishing from a Fork
+
+**Symptom:** 404 error when PR is from a forked repository.
+
+**Solution:** OIDC tokens are not available for forked PRs. Add a condition to skip publishing:
+
+```yml
+- uses: codfish/actions/npm-pr-version@v3
+  if: github.event.pull_request.head.repo.full_name == github.repository
+```
+
+#### Private Package with OIDC
+
+**Symptom:** 404 error on private package.
+
+**Solution:** OIDC trusted publishing only works with **public packages**. For private packages, use token-based
+authentication:
+
+```yml
+- uses: codfish/actions/npm-pr-version@v3
+  with:
+    npm-token: ${{ secrets.NPM_TOKEN }}
+```
+
+### Error: npm version too old
+
+**Symptom:**
+
+```txt
+npm ERR! --provenance flag is not supported
+```
+
+**Solution:** OIDC trusted publishing requires npm 11.5.1+. Use `setup-node-and-install@v3` which automatically upgrades
+npm to v11 for you:
+
+```yml
+- uses: codfish/actions/setup-node-and-install@v3
+  with:
+    node-version: lts/*
+```
+
+This action will upgrade npm from whatever version comes with Node.js to v11 (pinned to `^11.5.1`), ensuring OIDC
+compatibility.
+
+**Manual alternative:** If not using the setup action, upgrade npm yourself:
+
+```yml
+- run: npm install -g npm@^11.5.1
+```
+
+### Debugging OIDC Issues
+
+To debug OIDC authentication issues, check the workflow logs for:
+
+1. **OIDC environment variables** - Should see:
+
+```txt
+   🔐 Using OIDC trusted publishing (no npm-token provided)
+```
+
+2. **npm version** - Should be 11.5.1 or higher:
+
+```txt
+   npm version: 11.5.1
+```
+
+3. **Verify permissions** - Check workflow run permissions in GitHub UI
+
+4. **Check npm configuration** - Go to npmjs.com → Your Package → Publishing Access → Verify trusted publisher settings
+   match your workflow exactly