@codfish/actions 2.0.0 → 3.3.1

package/README.md

@@ -3,7 +3,7 @@
 A collection of reusable GitHub Actions for common development workflows. Each action is self-contained and designed for
 maximum reusability across different projects.
 
-<!-- prettier-ignore-start -->
+<!-- eslint-disable -->
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 ## Table of Contents
@@ -15,20 +15,22 @@ maximum reusability across different projects.
   - [setup-node-and-install](#setup-node-and-install)
 - [Contributing](#contributing)
 - [Example Workflow](#example-workflow)
+- [Maintenance](#maintenance)
+  - [Test pull requests in downstream apps before merging](#test-pull-requests-in-downstream-apps-before-merging)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
-<!-- prettier-ignore-end -->
+<!-- eslint-enable -->
 
 ## Usage
 
 Reference actions using the following format:
 
-```yaml
+```yml
 uses: codfish/actions/{action-name}@main
-uses: codfish/actions/{action-name}@v1
-uses: codfish/actions/{action-name}@v1.0.1
+uses: codfish/actions/{action-name}@v3
+uses: codfish/actions/{action-name}@v3.0.1
 uses: codfish/actions/{action-name}@feature-branch
-uses: codfish/actions/{action-name}@aff1a9d
+uses: codfish/actions/{action-name}@9f7cf1a3ff9f2838eff5ec9ac69b6ff277610bb2
 ```
 
 ## Available Actions
@@ -49,9 +51,9 @@ Creates or updates a comment in a pull request with optional tagging for upsert
 
 **Usage:**
 
-```yaml
+```yml
 - name: Comment on PR
-  uses: codfish/actions/comment@v1
+  uses: codfish/actions/comment@v3
   with:
     message: '✅ Build successful!'
     tag: 'build-status'
@@ -60,17 +62,17 @@ Creates or updates a comment in a pull request with optional tagging for upsert
 
 ### [npm-pr-version](./npm-publish-pr/)
 
-Publishes package with PR-specific version (0.0.0-PR-123--abc1234) using detected package manager (npm/yarn/pnpm) and
-automatically comments on PR
+Publishes package with PR-specific version (0.0.0-PR-123--abc1234) using detected package manager (npm/yarn/pnpm) or
+OIDC trusted publishing, and automatically comments on PR
 
 **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` |
 
 **Outputs:**
 
@@ -82,20 +84,25 @@ automatically comments on PR
 
 **Usage:**
 
-```yaml
-steps:
-  - uses: actions/checkout@v5
+```yml
+on: pull_request
 
-  - uses: codfish/actions/setup-node-and-install@v1
-    with:
-      node-version: lts/*
+jobs:
+  publish:
+    permissions:
+      id-token: write
+      pull-requests: write
 
-  - run: npm run build
+    steps:
+      - uses: actions/checkout@v6
 
-  - uses: codfish/actions/npm-pr-version@v1
-    with:
-      npm-token: ${{ secrets.NPM_TOKEN }}
-      github-token: ${{ secrets.GITHUB_TOKEN }}
+      - uses: codfish/actions/setup-node-and-install@v3
+        with:
+          node-version: lts/*
+
+      - run: npm run build
+
+      - uses: codfish/actions/npm-pr-version@v3
 ```
 
 ### [setup-node-and-install](./setup-node-and-install/)
@@ -105,29 +112,36 @@ intelligent caching, and version detection via input, .node-version, .nvmrc, or
 
 **Inputs:**
 
-| Input               | Description                                                                                                                          | Required | Default |
-| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | -------- | ------- |
-| `node-version`      | Node.js version to install (e.g. "24", "lts/\*"). Precedence: node-version input > .node-version > .nvmrc > package.json volta.node. | No       | -       |
-| `install-options`   | Extra command-line options to pass to npm/pnpm/yarn install.                                                                         | No       | -       |
-| `working-directory` | Directory containing package.json and lockfile.                                                                                      | No       | `.`     |
+| Input               | Description                                                                                                                                                                                                                                                                                                     | Required | Default |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- |
+| `node-version`      | Node.js version to install (e.g. "24", "lts/\*"). Precedence: node-version input > .node-version > .nvmrc > package.json volta.node.                                                                                                                                                                            | No       | -       |
+| `install-options`   | Extra command-line options to pass to npm/pnpm/yarn install.                                                                                                                                                                                                                                                    | No       | -       |
+| `working-directory` | Directory containing package.json and lockfile.                                                                                                                                                                                                                                                                 | No       | `.`     |
+| `registry-url`      | Optional registry URL to configure for publishing (e.g. "https://registry.npmjs.org/"). Creates .npmrc with NODE_AUTH_TOKEN placeholder. NOT recommended if using semantic-release (it handles auth independently). Only needed for publishing with manual npm publish or other non-semantic-release workflows. | No       | -       |
+| `upgrade-npm`       | Whether to upgrade npm to v11.5.1. This is required for OIDC trusted publishing but can be disabled if you want to shave off some run time and you are still using token-based authentication.                                                                                                                  | No       | `true`  |
 
 **Outputs:**
 
-| Output      | Description                                        |
-| ----------- | -------------------------------------------------- |
-| `cache-hit` | Whether the dependency cache was hit (true/false). |
+| Output          | Description                                        |
+| --------------- | -------------------------------------------------- |
+| `node-version`  | The installed node version.                        |
+| `cache-hit`     | Whether the dependency cache was hit (true/false). |
+| `pnpm-dest`     | Expanded path of pnpm dest.                        |
+| `pnpm-bin-dest` | Location of pnpm and pnpx command.                 |
 
 **Usage:**
 
-```yaml
+```yml
 steps:
-  - uses: actions/checkout@v5
+  - uses: actions/checkout@v6
+
+  # Will setup node, inferring node version from your codebase & installing your dependencies
+  - uses: codfish/actions/setup-node-and-install@v3
 
-  # will install latest Node v18.x
-  - uses: codfish/actions/setup-node-and-install@v1
+  # Or if you want to be explicit
+  - uses: codfish/actions/setup-node-and-install@v3
     with:
-      node-version: 18
-      cache-key-suffix: '-${{ github.head_ref || github.event.release.tag_name }}'
+      node-version: 24.4
 
   - run: npm test
 ```
@@ -145,53 +159,55 @@ Each action follows these conventions:
 
 ## Example Workflow
 
-Complete workflow using multiple actions together:
+Complete workflow using multiple actions together with secure OIDC trusted publishing:
 
-```yaml
-name: CI/CD Pipeline
-on:
-  pull_request:
-    types: [opened, synchronize]
+```yml
+name: Validate
+
+on: pull_request_target
 
 jobs:
-  test-and-publish:
+  # Build and test with untrusted PR code (no secrets)
+  build-and-test:
     runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v5
 
-      - uses: codfish/actions/setup-node-and-install@v1
+    permissions:
+      contents: read
+      pull-requests: write
+
+    steps:
+      - uses: actions/checkout@v6
         with:
-          node-version: 'lts/*'
+          ref: ${{ github.event.pull_request.head.sha }}
+
+      - uses: codfish/actions/setup-node-and-install@v3
 
       - name: Run tests
+        id: test
         run: |
-          npm test 2>&1 | tee test-output.txt
+          pnpm test 2>&1 | tee test-output.txt
           if grep -q "All tests passed" test-output.txt; then
             echo "status=✅ passed" >> $GITHUB_OUTPUT
           else
             echo "status=❌ failed" >> $GITHUB_OUTPUT
           fi
           echo "count=$(grep -c "✓\|√\|PASS" test-output.txt || echo "unknown")" >> $GITHUB_OUTPUT
-        id: test
 
       - name: Build package
-        run: npm run build
-
-      - name: Calculate build size
+        id: build
         run: |
+          pnpm build
+
           if [ -d "dist" ]; then
             size=$(du -sh dist | cut -f1)
           elif [ -d "build" ]; then
             size=$(du -sh build | cut -f1)
-          elif [ -f "package.json" ]; then
-            size=$(du -sh . --exclude=node_modules | cut -f1)
           else
             size="unknown"
           fi
           echo "size=$size" >> $GITHUB_OUTPUT
-        id: build
 
-      - uses: codfish/actions/comment@v1
+      - uses: codfish/actions/comment@v3
         with:
           message: |
             ## 🚀 **Build Summary**
@@ -204,9 +220,64 @@ jobs:
           tag: 'build-summary'
           upsert: true
 
-      - uses: codfish/actions/npm-pr-version@v1
+      - name: Create package tarball
+        run: pnpm pack
+
+      - uses: actions/upload-artifact@v4
         with:
-          npm-token: ${{ secrets.NPM_TOKEN }}
-          github-token: ${{ secrets.GITHUB_TOKEN }}
+          name: package-tarball
+          path: '*.tgz'
+          retention-days: 1
+
+  # Publish with secrets using only trusted base branch code
+  publish:
+    needs: build-and-test
+
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+      id-token: write
+      pull-requests: write
+
+    steps:
+      - uses: actions/checkout@v6
+        # No ref = uses base branch (trusted code only)
+
+      - uses: codfish/actions/setup-node-and-install@v3
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: package-tarball
+
+      - uses: codfish/actions/npm-pr-version@v3
+        with:
+          tarball: '*.tgz' # Secure: uses --ignore-scripts
           comment-tag: 'pr-package'
 ```
+
+## Maintenance
+
+> The release workflow automatically updates the major version tag (v3, v4, v5, etc.) to point to the latest release for
+> that major version. This allows users binding to the major version tag to automatically receive the most recent stable
+> minor/patch releases.
+
+This happens automatically in the [release workflow](.github/workflows/release.yml) after each successful release.
+
+If you need to update the major version tag manually:
+
+```sh
+git tag -fa v5 -m "Update v5 tag" && git push origin v5 --force
+```
+
+**Reference**: https://github.com/actions/toolkit/blob/main/docs/action-versioning.md#recommendations
+
+### Test pull requests in downstream apps before merging
+
+Our validation workflow builds and publishes a multi-arch Docker image to GitHub Container Registry for every pull
+request, tagging the image with the PR's branch name. You can point downstream repositories at this branch-tagged image
+to try changes before merging.
+
+```yml
+- uses: codfish/actions:<branch-name>
+```

package/bin/generate-docs.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 import fs from 'fs';
-import yaml from 'js-yaml';
+import yml from 'js-yaml';
 import path from 'path';
 
 /**
@@ -37,7 +37,7 @@ class DocumentationGenerator {
 
     try {
       const content = fs.readFileSync(actionFile, 'utf8');
-      const actionData = yaml.load(content);
+      const actionData = yml.load(content);
 
       return {
         directory: dirName,
@@ -68,12 +68,12 @@ class DocumentationGenerator {
 
       // Look for usage examples in various sections
       const patterns = [
-        // Look for "## Usage" section with yaml code block
-        /## Usage[\s\S]*?```yaml\n([\s\S]*?)\n```/i,
-        // Look for any yaml code block with "uses: "
-        /```yaml\n([\s\S]*?uses:\s*[.\w/-]+[\s\S]*?)\n```/i,
+        // Look for "## Usage" section with yml code block
+        /## Usage[\s\S]*?```yml\n([\s\S]*?)\n```/i,
+        // Look for any yml code block with "uses: "
+        /```yml\n([\s\S]*?uses:\s*[.\w/-]+[\s\S]*?)\n```/i,
         // Look for specific action usage
-        new RegExp(`\`\`\`yaml\\n([\\s\\S]*?uses:\\s*[^\\n]*${dirName}[\\s\\S]*?)\\n\`\`\``, 'i'),
+        new RegExp(`\`\`\`yml\\n([\\s\\S]*?uses:\\s*[^\\n]*${dirName}[\\s\\S]*?)\\n\`\`\``, 'i'),
       ];
 
       for (const pattern of patterns) {
@@ -84,7 +84,7 @@ class DocumentationGenerator {
 
           // If it doesn't start with a step name, add one
           if (!example.match(/^\s*-\s*name:/m) && !example.match(/^\s*-\s*uses:/m)) {
-            return `- uses: codfish/actions/${dirName}@v1\n${example.replace(/^/gm, '  ')}`;
+            return `- uses: codfish/actions/${dirName}@v3\n${example.replace(/^/gm, '  ')}`;
           }
 
           return example;
@@ -103,7 +103,7 @@ class DocumentationGenerator {
    * Generate a basic usage example based on action inputs
    */
   generateBasicExample(dirName, inputs = {}) {
-    let example = `- uses: codfish/actions/${dirName}@v1`;
+    let example = `- uses: codfish/actions/${dirName}@v3`;
 
     const inputKeys = Object.keys(inputs);
     if (inputKeys.length > 0) {
@@ -180,7 +180,7 @@ class DocumentationGenerator {
 
     // Add usage example
     if (usageExample) {
-      section += `**Usage:**\n\n\`\`\`yaml\n${usageExample}\n\`\`\`\n\n`;
+      section += `**Usage:**\n\n\`\`\`yml\n${usageExample}\n\`\`\`\n\n`;
     }
 
     return section;

package/comment/README.md

@@ -8,9 +8,9 @@ Creates or updates pull request comments with intelligent upsert functionality u
 
 See [action.yml](action.yml).
 
-```yaml
+```yml
 - name: Comment on PR
-  uses: codfish/actions/comment@v1
+  uses: codfish/actions/comment@v3
   with:
     message: '✅ Build successful!'
     tag: 'build-status'
@@ -33,8 +33,8 @@ See [action.yml](action.yml).
 
 ### Basic comment
 
-```yaml
-- uses: codfish/actions/comment@v1
+```yml
+- uses: codfish/actions/comment@v3
   with:
     message: 'Hello from GitHub Actions! 👋'
 ```
@@ -43,9 +43,9 @@ See [action.yml](action.yml).
 
 Use the `upsert` feature to update the same comment instead of creating multiple comments:
 
-```yaml
+```yml
 - name: Update build status
-  uses: codfish/actions/comment@v1
+  uses: codfish/actions/comment@v3
   with:
     message: |
       ## Build Status
@@ -55,7 +55,7 @@ Use the `upsert` feature to update the same comment instead of creating multiple
 
 # Later in the workflow...
 - name: Update build status
-  uses: codfish/actions/comment@v1
+  uses: codfish/actions/comment@v3
   with:
     message: |
       ## Build Status
@@ -66,8 +66,8 @@ Use the `upsert` feature to update the same comment instead of creating multiple
 
 ### Multi-line markdown comment
 
-```yaml
-- uses: codfish/actions/comment@v1
+```yml
+- uses: codfish/actions/comment@v3
   with:
     message: |
       ## 📊 Test Results

package/comment/action.yml

@@ -46,7 +46,7 @@ runs:
     - name: Check existing comments
       id: check-comments
       if: inputs.upsert == 'true'
-      uses: actions/github-script@v7
+      uses: actions/github-script@v8
       with:
         script: |
           try {
@@ -69,7 +69,7 @@ runs:
 
     - name: Update existing comment
       if: steps.check-comments.outputs.comment-id != null
-      uses: actions/github-script@v7
+      uses: actions/github-script@v8
       with:
         script: |
           try {
@@ -86,7 +86,7 @@ runs:
 
     - name: Create new comment
       if: steps.check-comments.outputs.comment-id == null
-      uses: actions/github-script@v7
+      uses: actions/github-script@v8
       with:
         script: |
           try {