Changeset 63438

Timestamp:

09/02/2026 06:21:17 PM (2 weeks ago)

Author:

lancewillett

Message:

Build/Test Tools: Allow PHPUnit workflows to test other repositories.

Add optional repository and ref inputs to the reusable PHPUnit and Gutenberg preparation workflows. Add a same-run overlay artifact for caller-provided tests.

Name prepared Gutenberg artifacts by ref, reject refs that cannot form artifact names, and retry Gutenberg downloads for older branches. Existing callers retain their current behavior.

Developed in: ​https://github.com/WordPress/wordpress-develop/pull/12862

Props lucatume.
Fixes #65964.

Location:

trunk/.github/workflows

Files:

• reusable-phpunit-tests-v3.yml (modified) (6 diffs)
• reusable-prepare-gutenberg.yml (modified) (5 diffs)

trunk/.github/workflows/reusable-phpunit-tests-v3.yml

@@ -14 +14 @@
         type: 'string'
         default: 'ubuntu-24.04'
+      repository:
+        description: 'The repository to check out and test. Defaults to the repository calling this workflow.'
+        required: false
+        type: 'string'
+        default: ''
+      # Also composes the Gutenberg build name, under the producer's constraint: a valid
+      # artifact name, so no slashes and none of : < > | * ? "
+      ref:
+        description: 'The branch, tag, or SHA to check out. Defaults to the ref that triggered the calling workflow.'
+        required: false
+        type: 'string'
+        default: ''
       php:
         description: 'The version of PHP to use, in the format of X.Y'
@@ -80 +92 @@
       gutenberg-sha:
         description: 'The immutable Gutenberg source SHA verified by the calling workflow.'
+        required: false
+        type: string
+        default: ''
+      overlay-artifact:
+        description: 'The name of a same-workflow artifact whose contents are unpacked over the checkout. Optional: for callers whose test files are not part of the repository being tested.'
         required: false
         type: string
@@ -113 +130 @@
   #
   # Performs the following steps:
+  # - Requires a ref when the caller points at another repository.
   # - Sets environment variables.
   # - Checks out the repository.
+  # - Unpacks the caller-provided overlay artifact over the checkout, if any.
   # - Downloads the prepared Gutenberg build provided by the calling workflow.
   # - Sets up Node.js.
@@ -141 +160 @@
 
     steps:
+      # `ref` otherwise falls back to checkout's own default, which for another repository is
+      # its default branch: a "WordPress 6.2" job would test trunk and report green.
+      - name: Require a ref when testing another repository
+        if: ${{ inputs.repository != '' && inputs.ref == '' }}
+        run: |
+          echo 'Testing another repository needs an explicit ref.' >&2
+          exit 1
+
+      # `ref` also composes the Gutenberg artifact name, so reject what that name cannot carry
+      # here rather than at a download step the job only reaches minutes later.
+      - name: Require a ref the artifact name accepts
+        if: ${{ inputs.ref != '' }}
+        env:
+          REF: ${{ inputs.ref }}
+        run: |
+          invalid='[/:<>|*?"\]'
+          if [[ "$REF" =~ $invalid ]]; then
+            echo "A ref that names an artifact cannot contain / : < > | * ? \" \\ - received: $REF" >&2
+            exit 1
+          fi
+
       - name: Configure environment variables
         run: |
@@ -149 +189 @@
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
+          repository: ${{ inputs.repository || github.repository }}
+          ref: ${{ inputs.ref }}
           show-progress: ${{ runner.debug == '1' && 'true' || 'false' }}
           persist-credentials: false
+
+      # If the caller specifies an overlay artifact then unpack it over the checkout.
+      - name: Download overlay artifact
+        if: inputs.overlay-artifact != ''
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          # Without a run ID, this action reads only from the caller's current workflow run.
+          name: ${{ inputs.overlay-artifact }}
+          path: .
+          digest-mismatch: error
 
       # Only WordPress 7.0+ include Gutenberg-maintained assets from a built zip file.
@@ -157 +209 @@
         uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
-          name: gutenberg-build
+          # Every branch in a run shares one artifact namespace, so the producer names each
+          # build after the ref it came from. Compose the same name here rather than taking
+          # it as an input: the two sides already agree on `ref`.
+          name: gutenberg-build${{ inputs.ref && format( '-{0}', inputs.ref ) || '' }}
           path: gutenberg
           digest-mismatch: error

trunk/.github/workflows/reusable-prepare-gutenberg.yml

@@ -7 +7 @@
 on:
   workflow_call:
+    inputs:
+      repository:
+        description: 'The repository to check out. Defaults to the repository calling this workflow.'
+        required: false
+        type: 'string'
+        default: ''
+      # Names the uploaded build too, so it must also be a valid artifact name: no slashes,
+      # and none of : < > | * ? " — a `refs/heads/trunk` or `feature/x` value fails the upload.
+      ref:
+        description: 'The branch, tag, or SHA to check out. Defaults to the commit that started the calling workflow run.'
+        required: false
+        type: 'string'
+        default: ''
     outputs:
       gutenberg-sha:
@@ -20 +33 @@
     name: Gutenberg
     runs-on: ubuntu-24.04
-    timeout-minutes: 10
+    # Two download attempts of up to six minutes each, where download.js retries internally.
+    timeout-minutes: 15
     outputs:
       gutenberg-sha: ${{ steps.download.outputs.gutenberg-sha }}
@@ -27 +41 @@
 
     steps:
+      # `ref` otherwise falls back to this run's commit, which another repository does not have.
+      - name: Require a ref when preparing another repository
+        if: ${{ inputs.repository != '' && inputs.ref == '' }}
+        run: |
+          echo 'Preparing another repository needs an explicit ref.' >&2
+          exit 1
+
+      # The upload names the artifact after `ref` and is this job's last step, so an unusable
+      # value would otherwise fail only once the whole download and verify has already run.
+      - name: Require a ref the artifact name accepts
+        if: ${{ inputs.ref != '' }}
+        env:
+          REF: ${{ inputs.ref }}
+        run: |
+          invalid='[/:<>|*?"\]'
+          if [[ "$REF" =~ $invalid ]]; then
+            echo "A ref that names an artifact cannot contain / : < > | * ? \" \\ - received: $REF" >&2
+            exit 1
+          fi
+
       - name: Checkout repository
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
-          # Resolve the Gutenberg ref from the exact commit that started this workflow run.
-          ref: ${{ github.sha }}
+          repository: ${{ inputs.repository || github.repository }}
+          # Resolve the Gutenberg ref from the exact commit that started this workflow run,
+          # unless the caller is preparing a build for a repository or branch of its own.
+          ref: ${{ inputs.ref || github.sha }}
           show-progress: ${{ runner.debug == '1' && 'true' || 'false' }}
           persist-credentials: false
@@ -43 +79 @@
         id: download
         run: |
-          node tools/gutenberg/download.js
+          # Branches whose download.js predates the in-script retry stream the blob straight
+          # into tar in a single attempt, so an interrupted stream fails the run outright.
+          # One retry, not two: where download.js does retry, it already allows three tries of
+          # two minutes each, and a third attempt here would outrun `timeout-minutes` and have
+          # the job killed rather than reported.
+          if ! node tools/gutenberg/download.js; then
+            echo 'Gutenberg download failed; retrying in 5 seconds...'
+            sleep 5
+            node tools/gutenberg/download.js
+          fi
+
           gutenberg_sha="$(tr -d '\n' < gutenberg/.gutenberg-hash)"
           if [[ ! "$gutenberg_sha" =~ ^[a-fA-F0-9]{40}$ ]]; then
@@ -54 +100 @@
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
-          name: gutenberg-build
+          # Every branch in a run shares one artifact namespace, so name the build after the
+          # ref it came from. The PHPUnit consumer composes the same name from its own `ref`,
+          # so the name is never passed between them.
+          name: gutenberg-build${{ inputs.ref && format( '-{0}', inputs.ref ) || '' }}
           path: gutenberg/
           if-no-files-found: error