chore: improve external contributor CI flow

.github/pull_request_template.md

@@ -11,16 +11,24 @@ Fixes `Issue URL`
 > [!WARNING]  
 > _If no issue exists, please create an issue first, and check with the maintainers if the issue is valid._
 
-## Automation
+## Testing
 
-/ok-to-test tags=""
+> [!NOTE]
+> Pull requests from forks run credential-free formatting, lint, type, and unit
+> checks after GitHub's workflow approval. A maintainer will start integration
+> tests or a deploy preview when needed. External contributors do not need to
+> add an `ok-to-test` label or run a slash command.
 
-### :mag: Cypress test results
-<!-- This is an auto-generated comment: Cypress test results  -->
-> [!CAUTION]  
-> If you modify the content in this section, you are likely to disrupt the CI result for your PR.
+Select the validation relevant to this change:
 
-<!-- end of auto-generated comment: Cypress test results  -->
+- [ ] Client unit tests
+- [ ] Server unit tests
+- [ ] Cypress
+- [ ] Playwright
+- [ ] Deploy preview
+- [ ] Not applicable
+
+Suggested Cypress tags or specs:
 
 
 ## Communication

.github/workflows/build-chromatic.yml

@@ -14,6 +14,9 @@ on:
 
 jobs:
   chromatic-deployment:
+    # Internal PRs only: the Chromatic project token is not available to fork
+    # PRs, so this job would always fail for external contributors.
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
     runs-on: ubuntu-latest
 
     steps:

.github/workflows/build-client-server.yml

@@ -2,7 +2,18 @@ name: Build Client, Server & Run only Cypress
 
 on:
   repository_dispatch:
-    types: [ci-test-limit-command]
+    types: [ci-test-limit-command, approve-ci-command]
+
+concurrency:
+  group: trusted-pr-ci-${{ github.event.client_payload.pull_request.number }}
+  cancel-in-progress: true
+
+permissions:
+  actions: read
+  contents: read
+  issues: write
+  packages: write
+  pull-requests: write
 
 jobs:
   file-check:
@@ -15,9 +26,66 @@ jobs:
       runId: ${{steps.args.outputs.runId}}
       matrix_count: ${{steps.matrix.outputs.matrix_count}}
       is-pg-build: ${{steps.args.outputs.is-pg-build}}
+      merge_sha: ${{ steps.approved.outputs.merge_sha }}
     steps:
-      - name: Checkout the head commit of the branch
+      - name: Checkout the PR merge commit
         uses: actions/checkout@v4
+        with:
+          ref: refs/pull/${{ github.event.client_payload.pull_request.number }}/merge
+          fetch-depth: 2
+
+      - name: Verify the commit approved by the maintainer
+        id: approved
+        env:
+          APPROVED_HEAD_SHA: ${{ github.event.client_payload.pull_request.head.sha }}
+          GH_TOKEN: ${{ github.token }}
+          PR_NUMBER: ${{ github.event.client_payload.pull_request.number }}
+        run: |
+          current_head_sha="$(
+            gh api "repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}" --jq .head.sha
+          )"
+          checked_out_head_sha="$(git rev-parse HEAD^2)"
+
+          if [[ "$current_head_sha" != "$APPROVED_HEAD_SHA" ]]; then
+            echo "::error::PR head changed after /approve-ci was issued. A maintainer must approve the new commit."
+            exit 1
+          fi
+
+          if [[ "$checked_out_head_sha" != "$APPROVED_HEAD_SHA" ]]; then
+            echo "::error::The checked-out merge commit does not contain the approved PR head."
+            exit 1
+          fi
+
+          echo "merge_sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
+          echo "Approved head: $APPROVED_HEAD_SHA" >> "$GITHUB_STEP_SUMMARY"
+          echo "Pinned merge commit: $(git rev-parse HEAD)" >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Record privileged CI approval
+        if: github.event.action == 'approve-ci-command'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const owner = context.repo.owner;
+            const repo = context.repo.repo;
+            const issue_number = context.payload.client_payload.pull_request.number;
+
+            await github.rest.issues.addLabels({
+              owner,
+              repo,
+              issue_number,
+              labels: ["ci-approved"],
+            });
+
+            try {
+              await github.rest.issues.removeLabel({
+                owner,
+                repo,
+                issue_number,
+                name: "awaiting-maintainer",
+              });
+            } catch (error) {
+              if (error.status !== 404) throw error;
+            }
 
       - name: Set matrix jobs
         id: matrix
@@ -41,7 +109,7 @@ jobs:
         id: files
         run: |
           git fetch origin release
-          git diff --name-only --diff-filter=A remotes/origin/release...${{ github.ref_name }} -- 'app/client/cypress/e2e' > diff
+          git diff --name-only --diff-filter=A remotes/origin/release...HEAD -- 'app/client/cypress/e2e' > diff
           echo "files_added=$(cat diff)" >> $GITHUB_OUTPUT
           cat diff
 
@@ -93,6 +161,7 @@ jobs:
     secrets: inherit
     with:
       pr: ${{fromJson(needs.file-check.outputs.pr)}}
+      checkout-ref: ${{ needs.file-check.outputs.merge_sha }}
       skip-tests: "true"
       is-pg-build: ${{fromJson(needs.file-check.outputs.is-pg-build)}}
 
@@ -104,6 +173,7 @@ jobs:
     secrets: inherit
     with:
       pr: ${{fromJson(needs.file-check.outputs.pr)}}
+      checkout-ref: ${{ needs.file-check.outputs.merge_sha }}
       skip-tests: "true"
 
   rts-build:
@@ -114,6 +184,7 @@ jobs:
     secrets: inherit
     with:
       pr: ${{fromJson(needs.file-check.outputs.pr)}}
+      checkout-ref: ${{ needs.file-check.outputs.merge_sha }}
 
   build-docker-image:
     needs: [file-check, client-build, server-build, rts-build]
@@ -124,6 +195,7 @@ jobs:
     secrets: inherit
     with:
       pr: ${{fromJson(needs.file-check.outputs.pr)}}
+      checkout-ref: ${{ needs.file-check.outputs.merge_sha }}
 
   ci-test-limited:
     needs: [file-check, build-docker-image]
@@ -134,6 +206,7 @@ jobs:
     secrets: inherit
     with:
       pr: ${{fromJson(needs.file-check.outputs.pr)}}
+      checkout-ref: ${{ needs.file-check.outputs.merge_sha }}
 
   ci-test-limited-existing-docker-image:
     needs: [file-check]
@@ -144,6 +217,7 @@ jobs:
     secrets: inherit
     with:
       pr: ${{fromJson(needs.file-check.outputs.pr)}}
+      checkout-ref: ${{ needs.file-check.outputs.merge_sha }}
       previous-workflow-run-id: ${{ fromJson(needs.file-check.outputs.runId) }}
 
   ci-test-limited-result:

.github/workflows/build-docker-image.yml

@@ -14,6 +14,11 @@ on:
         description: "This is the PR number in case the workflow is being called in a pull request"
         required: false
         type: number
+      checkout-ref:
+        description: "Immutable commit SHA to checkout for an approved external PR"
+        required: false
+        type: string
+        default: ""
 
 jobs:
   build-docker:
@@ -31,22 +36,28 @@ jobs:
     steps:
       # Check out merge commit
       - name: Fork based /ok-to-test checkout
-        if: inputs.pr != 0
+        if: inputs.checkout-ref == '' && inputs.pr != 0
         uses: actions/checkout@v4
         with:
           ref: "refs/pull/${{ inputs.pr }}/merge"
 
       # Checkout the code in the current branch in case the workflow is called because of a branch push event
       - name: Checkout the head commit of the branch
-        if: inputs.pr == 0 && inputs.branch == ''
+        if: inputs.checkout-ref == '' && inputs.pr == 0 && inputs.branch == ''
         uses: actions/checkout@v4
 
       - name: Checkout the specified branch
-        if: inputs.pr == 0 && inputs.branch != ''
+        if: inputs.checkout-ref == '' && inputs.pr == 0 && inputs.branch != ''
         uses: actions/checkout@v4
         with:
           ref: ${{ inputs.branch }}
 
+      - name: Checkout the approved immutable commit
+        if: inputs.checkout-ref != ''
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.checkout-ref }}
+
       - name: Download the client build artifact
         if: steps.run_result.outputs.run_result != 'success'
         uses: actions/download-artifact@v4

.github/workflows/build-storybook.yml

@@ -14,6 +14,9 @@ on:
 
 jobs:
   chromatic-deployment:
+    # Internal PRs only: the Storybook/Chromatic project token is not available
+    # to fork PRs, so this job would always fail for external contributors.
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
     runs-on: ubuntu-latest
 
     steps:

.github/workflows/ci-test-limited.yml

@@ -14,6 +14,11 @@ on:
         required: false
         type: number
         default: 0
+      checkout-ref:
+        description: "Immutable commit SHA to checkout for an approved external PR"
+        required: false
+        type: string
+        default: ""
   workflow_call:
     inputs:
       pr:
@@ -25,6 +30,11 @@ on:
         required: false
         type: number
         default: 0
+      checkout-ref:
+        description: "Immutable commit SHA to checkout for an approved external PR"
+        required: false
+        type: string
+        default: ""
 
 jobs:
   ci-test-limited:
@@ -62,16 +72,22 @@ jobs:
 
       # Check out merge commit
       - name: Fork based /ok-to-test checkout
-        if: inputs.pr != 0
+        if: inputs.checkout-ref == '' && inputs.pr != 0
         uses: actions/checkout@v4
         with:
           ref: "refs/pull/${{ inputs.pr }}/merge"
 
       # Checkout the code in the current branch in case the workflow is called because of a branch push event
       - name: Checkout the head commit of the branch
-        if: inputs.pr == 0
+        if: inputs.checkout-ref == '' && inputs.pr == 0
         uses: actions/checkout@v4
 
+      - name: Checkout the approved immutable commit
+        if: inputs.checkout-ref != ''
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.checkout-ref }}
+
       # Timestamp will be used to create cache key
       - id: timestamp
         run: echo "timestamp=$(date +'%Y-%m-%dT%H:%M:%S')" >> $GITHUB_OUTPUT

.github/workflows/client-build.yml

@@ -16,6 +16,11 @@ on:
         description: "This is the branch to be used for the build."
         required: false
         type: string
+      checkout-ref:
+        description: "Immutable commit SHA to checkout for an approved external PR"
+        required: false
+        type: string
+        default: ""
 
 permissions:
   contents: read
@@ -45,26 +50,33 @@ jobs:
 
       # Check out merge commit with the base branch in case this workflow is invoked via pull request
       - name: Checkout the merged commit from PR and base branch
-        if: inputs.pr != 0
+        if: inputs.checkout-ref == '' && inputs.pr != 0
         uses: actions/checkout@v4
         with:
           fetch-tags: true
           ref: refs/pull/${{ inputs.pr }}/merge
 
       # Check out the specified branch in case this workflow is called by another workflow
       - name: Checkout the specified branch
-        if: inputs.pr == 0 && inputs.branch != ''
+        if: inputs.checkout-ref == '' && inputs.pr == 0 && inputs.branch != ''
         uses: actions/checkout@v4
         with:
           fetch-tags: true
           ref: ${{ inputs.branch }}
 
       # Checkout the code in the current branch in case the workflow is called because of a branch push event
       - name: Checkout the head commit of the branch
-        if: inputs.pr == 0 && inputs.branch == ''
+        if: inputs.checkout-ref == '' && inputs.pr == 0 && inputs.branch == ''
+        uses: actions/checkout@v4
+        with:
+          fetch-tags: true
+
+      - name: Checkout the approved immutable commit
+        if: inputs.checkout-ref != ''
         uses: actions/checkout@v4
         with:
           fetch-tags: true
+          ref: ${{ inputs.checkout-ref }}
 
       - name: Get changed files in the client folder
         id: changed-files-specific