From bcbf42a681d54499a83e15207b43cc5039c5ca95 Mon Sep 17 00:00:00 2001
From: teor <teor@riseup.net>
Date: Tue, 21 Nov 2023 19:14:13 +1000
Subject: [PATCH] Allow external PRs to pass Docs build and deploy

---
 .../docs-deploy-firebase.patch-external.yml   | 30 +++++++++++++++++++
 .../workflows/docs-deploy-firebase.patch.yml  |  9 ++++--
 .github/workflows/docs-deploy-firebase.yml    | 13 ++++++--
 3 files changed, 47 insertions(+), 5 deletions(-)
 create mode 100644 .github/workflows/docs-deploy-firebase.patch-external.yml

diff --git a/.github/workflows/docs-deploy-firebase.patch-external.yml b/.github/workflows/docs-deploy-firebase.patch-external.yml
new file mode 100644
index 00000000000..706f24d694c
--- /dev/null
+++ b/.github/workflows/docs-deploy-firebase.patch-external.yml
@@ -0,0 +1,30 @@
+# Workflow patches for skipping Google Cloud docs updates on PRs from external repositories.
+name: Docs
+
+# Run on PRs from external repositories, let them pass, and then Mergify will check them.
+# GitHub doesn't support filtering workflows by source branch names, so we have to do it for each
+# job.
+on:
+  pull_request:
+
+# IMPORTANT
+#
+# These job names must be kept in sync with the `.patch.yml` and `.yml` files.
+jobs:
+  build-docs-book:
+    name: Build and Deploy Zebra Book Docs
+    # Only run on PRs from external repositories.
+    # (github.ref is always a local branch, so this check will skip non-PRs as well.)
+    if: ${{ !contains(github.head_ref || github.ref, 'refs/heads/') }}
+    runs-on: ubuntu-latest
+    steps:
+      - run: 'echo "No build required"'
+
+  build-docs-internal:
+    name: Build and Deploy Zebra Internal Docs
+    # This dependency allows all these jobs to depend on a single condition, making it easier to
+    # change.
+    needs: build-docs-book
+    runs-on: ubuntu-latest
+    steps:
+      - run: 'echo "No build required"'
diff --git a/.github/workflows/docs-deploy-firebase.patch.yml b/.github/workflows/docs-deploy-firebase.patch.yml
index 4f6a0c2db8f..ed8bba560b5 100644
--- a/.github/workflows/docs-deploy-firebase.patch.yml
+++ b/.github/workflows/docs-deploy-firebase.patch.yml
@@ -1,9 +1,10 @@
+# Workflow patches for skipping Google Cloud docs updates when docs, Rust code, or dependencies
+# aren't modified in a PR.
 name: Docs
 
+# Run on PRs with unmodified docs, code, and dependency files.
 on:
   pull_request:
-    branches:
-      - main
     paths-ignore:
       # doc source files
       - 'book/**'
@@ -20,6 +21,9 @@ on:
       # workflow definitions
       - '.github/workflows/docs-deploy-firebase.yml'
 
+# IMPORTANT
+#
+# These job names must be kept in sync with the `.patch-external.yml` and `.yml` files.
 jobs:
   build-docs-book:
     name: Build and Deploy Zebra Book Docs
@@ -29,7 +33,6 @@ jobs:
 
   build-docs-internal:
     name: Build and Deploy Zebra Internal Docs
-    timeout-minutes: 45
     runs-on: ubuntu-latest
     steps:
       - run: 'echo "No build required"'
diff --git a/.github/workflows/docs-deploy-firebase.yml b/.github/workflows/docs-deploy-firebase.yml
index e6d0220dcba..f81e48bc263 100644
--- a/.github/workflows/docs-deploy-firebase.yml
+++ b/.github/workflows/docs-deploy-firebase.yml
@@ -1,3 +1,5 @@
+# Google Cloud docs updates that run when docs, Rust code, or dependencies are modified,
+# but only on PRs from the ZcashFoundation/zebra repository. (External PRs are deployed by mergify.)
 name: Docs
 
 # Ensures that only one workflow task will run at a time. Previous deployments, if
@@ -9,7 +11,9 @@ concurrency:
 
 on:
   workflow_dispatch:
+
   push:
+    # Skip main branch updates where docs, Rust code, and dependencies aren't modified.
     branches:
       - main
     paths:
@@ -29,8 +33,7 @@ on:
       - '.github/workflows/docs-deploy-firebase.yml'
 
   pull_request:
-    branches:
-      - main
+    # Skip PRs where docs, Rust code, and dependencies aren't modified.
     paths:
       # doc source files
       - 'book/**'
@@ -60,9 +63,14 @@ env:
   # https://github.com/ZcashFoundation/zebra/blob/main/.cargo/config.toml#L87
   RUSTDOCFLAGS: --html-in-header katex-header.html -D warnings -A rustdoc::private_intra_doc_links
 
+# IMPORTANT
+#
+# These job names must be kept in sync with the `.patch.yml` and `.patch-external.yml` files.
 jobs:
   build-docs-book:
     name: Build and Deploy Zebra Book Docs
+    # Skip PRs from external repositories, let them pass, and then Mergify will check them
+    if: ${{ contains(github.head_ref || github.ref, 'refs/heads/') }}
     timeout-minutes: 5
     runs-on: ubuntu-latest
     permissions:
@@ -116,6 +124,7 @@ jobs:
 
   build-docs-internal:
     name: Build and Deploy Zebra Internal Docs
+    if: ${{ contains(github.head_ref || github.ref, 'refs/heads/') }}
     timeout-minutes: 45
     runs-on: ubuntu-latest
     permissions: