Harden fork-safe preview workflows

Author: adamziel

.github/workflows/preview-build.yml

@@ -67,19 +67,19 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
         with:
           # Untrusted code: never persist credentials.
           persist-credentials: false
           fetch-depth: ${{ inputs.fetch-depth }}
 
       - if: ${{ inputs.node-version != '' }}
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
         with:
           node-version: ${{ inputs.node-version }}
 
       - if: ${{ inputs.php-version != '' }}
-        uses: shivammathur/setup-php@v2
+        uses: shivammathur/setup-php@728c6c6b8cf02c2e48117716a91ee48313958a19 # v2
         with:
           php-version: ${{ inputs.php-version }}
 
@@ -124,6 +124,7 @@ jobs:
             fi
             cp "$src" "$bundle/zips/$name.zip"
             echo "Staged: $name.zip ($(wc -c <"$bundle/zips/$name.zip") bytes)"
+            unzip -l "$bundle/zips/$name.zip"
           done <<< "$ARTIFACTS_INPUT"
 
           if [ -z "$(ls -A "$bundle/zips")" ]; then
@@ -144,7 +145,7 @@ jobs:
           fi
 
       - name: Upload artifact bundle
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
         with:
           # Single bundle keeps upload-artifact's static step count happy and
           # the publish workflow only needs to find one artifact, not N.

.github/workflows/preview-publish.yml

@@ -61,12 +61,12 @@ permissions:
 jobs:
   publish:
     runs-on: ubuntu-latest
-    if: github.event_name == 'workflow_run'
     steps:
       - name: Guard against misuse
-        # Defense in depth: the job-level `if` already gates on workflow_run,
-        # but we also want a loud failure (not a silent skip) if a caller
-        # wires this up via pull_request_target or schedule.
+        # This workflow is privileged. It may only run after an unprivileged
+        # pull_request build completed. Do not convert this to a job-level
+        # `if`: misconfigured callers should see a loud failure, not a
+        # silently skipped publish job.
         shell: bash
         env:
           EVENT_NAME: ${{ github.event_name }}
@@ -96,6 +96,7 @@ jobs:
           BLUEPRINT: ${{ inputs.blueprint }}
           KIND: ${{ inputs.kind }}
           FROM_ARTIFACT: ${{ inputs.blueprint-from-artifact }}
+          ARTIFACTS_TO_KEEP: ${{ inputs.artifacts-to-keep }}
         run: |
           set -euo pipefail
           set_count=0
@@ -110,11 +111,17 @@ jobs:
             echo "::error::kind must be 'plugin' or 'theme', got: $KIND" >&2
             exit 1
           fi
+          if [ "$ARTIFACTS_TO_KEEP" != "keep-all" ]; then
+            if ! [[ "$ARTIFACTS_TO_KEEP" =~ ^[0-9]+$ ]] || [ "$ARTIFACTS_TO_KEEP" -lt 1 ]; then
+              echo "::error::artifacts-to-keep must be a positive integer or 'keep-all', got: $ARTIFACTS_TO_KEEP" >&2
+              exit 1
+            fi
+          fi
 
       - name: Identify artifact bundle
         id: meta
         if: env.SKIP != '1'
-        uses: actions/github-script@v7
+        uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7
         env:
           SOURCE_RUN_ID: ${{ github.event.workflow_run.id }}
         with:
@@ -303,7 +310,7 @@ jobs:
 
       - name: Post Playground preview button
         if: env.SKIP != '1'
-        uses: WordPress/action-wp-playground-pr-preview@v2
+        uses: WordPress/action-wp-playground-pr-preview@c8607529dac8d2bf9a1e8493865fc97cd1c3c87b # v2
         with:
           mode: ${{ inputs.mode }}
           blueprint: ${{ steps.blueprint.outputs.blueprint }}

README.md

@@ -385,14 +385,35 @@ Two kinds of public URL work:
 
 The action handles (1) directly. The two reusable workflows handle (2) end-to-end: they run your build, upload the result to a `ci-artifacts` prerelease, and call the action with a Blueprint pointing at the resulting URL.
 
-### Two-workflow split (build path only)
-
-GitHub doesn't let one workflow simultaneously (a) run untrusted code from a fork PR and (b) write to releases or PR comments. The build path therefore splits:
-
-- **Build workflow** runs on `pull_request`, `permissions: contents: read`. Untrusted PR code executes here. The reusable workflow declares `contents: read` as a *ceiling*, so callers can't accidentally elevate it.
-- **Publish workflow** runs on `workflow_run`, `permissions: contents: write` + `pull-requests: write`. Never checks out PR code. GitHub reads its YAML from the *default branch* (security guarantee), so PRs can't tamper with what runs here.
-
-The publish workflow has a runtime guard that **fails loudly** if invoked from any trigger other than `workflow_run`. Misconfigured callers (e.g. someone reaches for `pull_request_target`) get a red ❌ instead of a silent compromise.
+### Fork safety model (build path only)
+
+GitHub doesn't let one workflow simultaneously (a) run untrusted code from a
+fork PR and (b) write to releases or PR comments. The build path therefore
+splits the work at the artifact boundary:
+
+- **Build workflow** runs on `pull_request`, `permissions: contents: read`.
+  It checks out the PR head, runs your `build-command`, validates that the
+  expected zip(s) exist, logs `unzip -l` for inspection, and uploads a single
+  bundle artifact. It has no secrets and does not persist checkout credentials.
+- **Publish workflow** runs on `workflow_run`, `permissions: contents: write`
+  + `pull-requests: write`. It never checks out PR code. GitHub reads this
+  workflow from the default branch, so a fork PR cannot change the privileged
+  publish logic in the same PR.
+- **Artifact bundle** is the only handoff from untrusted to trusted code. The
+  publish workflow treats it as opaque bytes: it uploads the zip(s), substitutes
+  their URLs into a Blueprint, and lets Playground run them later inside its
+  browser sandbox.
+
+The publish workflow has a runtime guard that **fails loudly** if invoked from
+any trigger other than `workflow_run`, or if the source run was not a successful
+`pull_request` run. Misconfigured callers (for example someone reaches for
+`pull_request_target`) get a red failure instead of a silent skip.
+
+Because the publish workflow is privileged, its third-party action references
+are pinned to commit SHAs. This avoids granting write permissions to a moved
+major-version tag. The internal button action is also called through an
+immutable v2 commit; v3 adds the reusable workflow layer around the same button
+action behavior.
 
 ### Trigger model and security
 
@@ -407,6 +428,11 @@ The publish workflow has a runtime guard that **fails loudly** if invoked from a
 
 Translation: the action does not require any trust in PR code. The zip is treated as opaque bytes everywhere except inside the Playground iframe, where the WebAssembly sandbox is the actual mitigation.
 
+For public repositories, release assets are public. A fork PR can therefore
+cause its built zip to be hosted on the repository's `ci-artifacts` prerelease
+until cleanup removes it. That is the tradeoff that makes one-click browser
+previews possible for fork contributors.
+
 `{{ARTIFACT_URL:<name>}}` substitution uses `JSON.stringify(url).slice(1, -1)`, so any character that could break JSON parsing is escaped. The `"{{...}}"` template convention is non-breaking and produces valid JSON for any URL.
 
 The `ci-artifacts` release is created as a **`--prerelease`**, not a draft. Prerelease assets are publicly downloadable on first run; draft assets require auth and Playground can't read them. The action handles this for you on first use; existing draft releases need a one-time conversion (see [Migrating](#migrating-from-older-usage)).
@@ -471,7 +497,7 @@ Runs in the privileged `workflow_run` context, exposes the artifact bundle's zip
 | `blueprint` | one of three‡ | — | Blueprint JSON template. Use `{{ARTIFACT_URL:<name>}}` placeholders inside double quotes. |
 | `kind` | one of three‡ | — | `plugin` or `theme`. Shortcut: requires exactly one zip in the bundle, generates an `installPlugin`/`installTheme` step with `activate: true`. |
 | `blueprint-from-artifact` | one of three‡ | `false` | When `true`, read `blueprint.json` from the artifact bundle (requires `blueprint-from-build:` on the build side). |
-| `artifacts-to-keep` | no | `2` | Distinct PR commits worth of zips to keep on the release. Older zips for the same PR get pruned. Set to `keep-all` to disable cleanup. |
+| `artifacts-to-keep` | no | `2` | Positive integer number of distinct PR commits worth of zips to keep on the release. Older zips for the same PR get pruned. Set to `keep-all` to disable cleanup. |
 | `release-tag` | no | `ci-artifacts` | Tag used to host artifacts publicly. Auto-created as a prerelease on first use. |
 | `mode` | no | `append-to-description` | `append-to-description` or `comment`. |
 
@@ -515,13 +541,15 @@ All variables except `PLAYGROUND_BUTTON` are HTML-escaped before substitution.
 - **Two workflow files when there's a build step.** GitHub's permission model around fork PRs makes this unavoidable. The reusable workflows minimise but don't eliminate the boilerplate.
 - **Permissions ceiling is rigid.** Reusable workflows declare a max permission set; callers can match but not extend. Almost certainly a feature, but worth naming if you need the publish workflow to also push tags.
 - **Build and publish workflows must be pinned to compatible versions.** The artifact-naming format is the implicit interface between them. Use the same `@v3` (or branch ref) in both.
+- **Fork PR build output becomes public.** The publish workflow never trusts the zip, but it does upload it to a public release URL so Playground can fetch it. Keep `artifacts-to-keep` low unless you deliberately want longer retention.
 - **`{{ARTIFACT_URL:<name>}}` substitution is the only template feature.** No conditionals, no loops, no other placeholders. For per-PR variable shapes, write the blueprint at build time and use `blueprint-from-artifact: true`.
 - **One zip per `artifacts` entry.** Multi-file install bundles still need a hand-rolled flow.
 - **Plugin zips must extract to a slug-named folder.** When you `zip -r my-plugin.zip .` from inside the plugin dir, the zip contents are at the root, and Playground will install them with no slug folder. Wrap with a directory: `mkdir stage/my-plugin && rsync -a ./ stage/my-plugin/ && (cd stage && zip -r ../my-plugin.zip my-plugin)`.
 - **Vite/webpack assets need stable filenames.** Playground enqueues from a fixed path, so disable hashing on the entry file (`rollupOptions.output.entryFileNames: 'admin.js'`) or read the build manifest in PHP.
 - **Hidden directories are skipped by `actions/upload-artifact@v4`.** If you stage your bundle in a `.foo/` directory it'll silently produce an empty artifact. Use a non-hidden name.
 - **`fetch-depth: 0` is required for diffs.** The default checkout is shallow (depth 1). Diffs against the PR base ref need full history, otherwise `git diff` fails with "no merge base."
 - **The `ci-artifacts` release is shared across all PRs.** Each PR's zips are unique (`pr-<N>-<SHA>-<name>.zip`); cleanup keeps the N most recent commit-sets per PR.
+- **`artifacts-to-keep` must be a positive integer or `keep-all`.** `0`, negative numbers, and arbitrary strings fail before any release assets are uploaded.
 - **`workflow_run`-triggered workflows always read their YAML from the default branch.** Workflow changes on a PR branch don't take effect until merged. Test publish-side changes on a scratch repo first.
 - **Private repos won't work.** Playground runs in the user's browser and needs unauthenticated download URLs. `git:directory` and release assets in private repos both require auth Playground doesn't have. Make the repo public or self-host the zip.