From d0f10c3e9591104b4d94246d5205ad6df3c89ec6 Mon Sep 17 00:00:00 2001
From: XiaoYun Zhang <xiaoyuz@microsoft.com>
Date: Wed, 7 Oct 2026 14:11:23 -0700
Subject: [PATCH] Accept exact source SHA for Pages deployments

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
---
 .github/workflows/pages.yml | 18 +++++++++++++++++-
 README.md                   | 27 ++++++++++++++++++++++-----
 2 files changed, 39 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml
index 2dad33c..90d606f 100644
--- a/.github/workflows/pages.yml
+++ b/.github/workflows/pages.yml
@@ -6,6 +6,11 @@ on:
   pull_request:
     branches: [main]
   workflow_dispatch:
+    inputs:
+      source_sha:
+        description: Exact 40-character RazorConsole/RazorConsole commit SHA (defaults to main)
+        required: false
+        type: string
   schedule:
     - cron: '17 5 * * *'
 
@@ -18,7 +23,7 @@ concurrency:
 
 env:
   SOURCE_REPOSITORY: RazorConsole/RazorConsole
-  SOURCE_REF: main
+  SOURCE_REF: ${{ github.event_name == 'workflow_dispatch' && inputs.source_sha || 'main' }}
   VITE_SITE_URL: https://razorconsole.github.io
   VITE_BASE: /
   VITE_ROUTER_BASENAME: /
@@ -30,6 +35,17 @@ jobs:
     outputs:
       source-sha: ${{ steps.source.outputs.sha }}
     steps:
+      - name: Validate requested source revision
+        if: github.event_name == 'workflow_dispatch' && inputs.source_sha != ''
+        shell: bash
+        env:
+          REQUESTED_SOURCE_SHA: ${{ inputs.source_sha }}
+        run: |
+          if [[ ! "$REQUESTED_SOURCE_SHA" =~ ^[0-9a-fA-F]{40}$ ]]; then
+            echo "::error title=Invalid source_sha::source_sha must be exactly 40 hexadecimal characters"
+            exit 1
+          fi
+
       - name: Check out website source
         uses: actions/checkout@v7
         with:
diff --git a/README.md b/README.md
index ebf9154..f8a94e0 100644
--- a/README.md
+++ b/README.md
@@ -24,8 +24,25 @@ Before the first deployment, an organization owner must open **Settings → Page
 deployment** and set **Source** to **GitHub Actions**. The existing project site should not be changed
 until the root URL and representative routes return HTTP 200.
 
-To recover or immediately pick up a source change, run **Build and deploy organization site** from
-the Actions tab on the `main` branch. GitHub's repository-scoped `GITHUB_TOKEN` cannot trigger a
-workflow in another repository, so immediate source-driven deployments would require an explicitly
-managed GitHub App or fine-grained token. The scheduled and manual paths require no cross-repository
-secret.
+To recover or immediately deploy a known source revision, run **Build and deploy organization
+site** from the Actions tab on this repository's `main` branch. Set `source_sha` to the full
+40-character hexadecimal commit SHA from `RazorConsole/RazorConsole`; leaving it empty builds that
+repository's current `main`. The workflow validates a provided value before checkout, and its
+summary records both the requested ref and the commit that was actually built.
+
+Source-repository automation can request the same exact revision through the workflow dispatch API:
+
+```json
+{
+  "ref": "main",
+  "inputs": {
+    "source_sha": "0123456789abcdef0123456789abcdef01234567"
+  }
+}
+```
+
+The caller must replace the example with the source event's full commit SHA and authenticate as a
+GitHub App or fine-grained token that can dispatch Actions workflows in this repository. A
+repository-scoped `GITHUB_TOKEN` from `RazorConsole/RazorConsole` cannot trigger a workflow in this
+repository. Scheduled and push runs continue to build source `main`, and the manual fallback
+requires no cross-repository secret.