Link percy builds with a specific pull request; remove unnecessary ar…

…tifact compression; Note manual status check application as to-be-removed; run percy only when certain files are changed

.github/workflows/percy-prepare.yml

@@ -0,0 +1,48 @@
+name: "Prepare Percy build"
+
+on:
+  workflow_call:
+    inputs: 
+      pr_number:
+        required: true
+        type: number
+      repository: 
+        required: true
+        type: string
+      commitsh:
+        required: true
+        type: string
+
+jobs:
+  copy_artifact:
+    name: Prepare build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+        with:
+          sparse-checkout: |
+            templates/docs/examples/
+            scss/
+          ref: ${{ github.event.inputs.commitsh }}
+          repository: ${{ github.event.inputs.repository }}
+
+      - name: Populate artifact directory
+        run: |
+          mkdir -p artifact
+          cp -R templates/docs/examples/ scss/ artifact/.
+        
+      # Archive the PR number associated with this workflow since it won't be available in the base workflow context
+      # https://github.com/orgs/community/discussions/25220
+      - name: Archive PR data
+        if: github.event_name=='pull_request'
+        working-directory: artifact
+        run: |
+          echo ${{ inputs.pr_number }} > pr_num.txt
+          echo ${{ inputs.commitsh }} > pr_head_sha.txt
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: "percy-testing-web-artifact"
+          path: artifact/*

.github/workflows/percy-snapshot/action.yml

@@ -1,6 +1,9 @@
 name: Percy Snapshot
 description: Starts Vanilla local server, captures example snapshots, & uploads them to Percy
 inputs:
+  pr_number:
+    required: false
+    description: Identifier of a pull request to associate with this Percy build. I.E. github.com/{repo}/pull/{pr_number}
   commitsh:
     required: true
     description: SHA signature of commit triggering the build
@@ -81,6 +84,8 @@ runs:
         PERCY_BRANCH: ${{ inputs.branch_name }}
         PERCY_COMMIT: ${{ inputs.commitsh }}
         PERCY_CLIENT_ERROR_LOGS: false
+        # If PR number is set & a Percy-GHA integration is set up, this allows Percy to set status on the PR
+        PERCY_PULL_REQUEST: ${{ inputs.pr_number }}
       run: |
         set -e
         # Start a percy build and capture the stdout

.github/workflows/pr-percy-prepare-label.yml

@@ -0,0 +1,22 @@
+# This workflow ensures Percy is executed against PRs with the Percy required label, regardless of which paths were changed
+name: "Percy [labeled]"
+
+on:
+  pull_request:
+    branches:
+      - main
+    types:
+        # workflow runs after a label is added to the PR, or when a commit is added to a PR with the Percy label
+      - labeled
+      - ready_for_review
+      - synchronize
+
+jobs:
+  copy_artifact:
+    name: Prepare build
+    if: contains(github.event.pull_request.labels.*.name, vars.PERCY_TEST_REQUESTED_LABEL_NAME)
+    uses: ./.github/workflows/percy-prepare.yml
+    with:
+      pr_number: ${{ github.event.number }}
+      repository: ${{ github.repository }}
+      commitsh: ${{ github.event.pull_request.head.sha }}

.github/workflows/pr-percy-prepare-push.yml

@@ -0,0 +1,26 @@
+# This workflow runs Percy against non-draft PRs that have changes in relevant examples filepaths.
+name: "Percy [pushed]"
+
+on:
+  pull_request:
+    branches:
+      - main
+    paths:
+      - "templates/docs/examples/**"
+      - "scss/**"
+    types:
+      - opened
+      - ready_for_review
+      - synchronize
+
+jobs:
+  copy_artifact:
+    name: Prepare build
+    # Ignore draft PRS and PRs with the Percy label
+    # If we run tests against PRs with the Percy label, we will run tests twice (test is also ran by the labelling workflow)
+    if: ${{ !github.event.pull_request.draft && !contains(github.event.pull_request.labels.*.name, vars.PERCY_TEST_REQUESTED_LABEL_NAME) }}
+    uses: ./.github/workflows/percy-prepare.yml
+    with:
+      pr_number: ${{ github.event.number }}
+      repository: ${{ github.repository }}
+      commitsh: ${{ github.event.pull_request.head.sha }}

.github/workflows/pr-percy-snapshots.yml

@@ -3,7 +3,8 @@ name: "Percy screenshots"
 on:
   workflow_run:
     workflows:
-      - "Prepare Percy build"
+      - "Percy [pushed]"
+      - "Percy [labeled]"
     types:
       - completed
 
@@ -14,27 +15,31 @@ jobs:
     runs-on: ubuntu-latest
     outputs:
       pr_head_sha: ${{ steps.get_pr_data.outputs.sha }}
+      pr_number: ${{ steps.get_pr_data.outputs.pr_number }}
       percy_build_link: ${{ steps.percy_snapshot.outputs.build_link }}
       percy_org_id: ${{ steps.percy_snapshot.outputs.org_id }}
       percy_build_id: ${{ steps.percy_snapshot.outputs.build_id }}
     steps:
       - name: Checkout SCM
         uses: actions/checkout@v4
 
+      - name: Remove SCM directories that will be replaced by artifact files
+        run: |
+          set -e
+          rm -rf templates/docs/examples/ scss/
+
       - name: Download artifact from workflow run
         uses: actions/download-artifact@v4
         with:
-          name: "web-artifact-${{ github.event.workflow_run.id }}"
+          name: "percy-testing-web-artifact"
           github-token: ${{ secrets.GITHUB_TOKEN }}
           repository: ${{ github.event.workflow_run.repository.full_name }}
           run-id: ${{ github.event.workflow_run.id }}
 
-      - name: Replace SCM files with artifact files
+      - name: Move artifact files into place to replace SCM
         run: |
           set -e
-          rm -rf templates/docs/examples/ scss/
-          tar xzf build.tar.gz
-          rm build.tar.gz
+          # artifact directory contains `scss/`, `/examples`, `pr_num.txt`, and `pr_head_sha.txt`. `/examples` must be moved to `templates/docs/`.
           mv examples/ templates/docs/.
 
       - name: Get PR data
@@ -43,17 +48,19 @@ jobs:
         run: |
           set -e
           echo "sha=$(cat pr_head_sha.txt)" >> $GITHUB_OUTPUT
-          echo "pr=$(cat pr_num.txt)" >> $GITHUB_OUTPUT
+          echo "pr_number=$(cat pr_num.txt)" >> $GITHUB_OUTPUT
 
       - name: Take snapshots & upload to Percy
         id: percy_snapshot
-        uses: './.github/workflows/percy-snapshot'
+        uses: "./.github/workflows/percy-snapshot"
         with:
-          branch_name: "pull/${{ steps.get_pr_data.outputs.pr }}"
+          branch_name: "pull/${{ steps.get_pr_data.outputs.pr_number }}"
+          pr_number: ${{ steps.get_pr_data.outputs.pr_number }}
           commitsh: ${{ steps.get_pr_data.outputs.sha }}
           percy_token_write: ${{ secrets.PERCY_TOKEN_WRITE }}
 
   # Add a check to the PR to show that screenshots were sent to Percy
+  # Manual status check to be removed once IS-GHA integration is complete
   # https://docs.github.com/en/rest/checks/runs?apiVersion=2022-11-28#create-a-check-run
   apply_pr_check:
     name: Apply PR check
@@ -65,7 +72,7 @@ jobs:
         id: create_check_run
         uses: octokit/request-action@v2.x
         with:
-          route: POST /repos/${{github.repository}}/check-runs
+          route: POST /repos/${{ github.repository }}/check-runs
           owner: octokit
           repo: request-action
           name: "percy_upload"