From 1754a4e6564d5ef22b53a043d0db60ba1043c620 Mon Sep 17 00:00:00 2001
From: Kyle Conroy <kyle@conroy.org>
Date: Thu, 16 Apr 2026 21:55:12 -0700
Subject: [PATCH] Skip CI/RTD builds when the change is irrelevant

- Add paths-ignore for docs/** and .readthedocs.yaml to the go, buf,
  kotlin, python, and typescript workflows so doc-only PRs don't
  spin up the Go test matrix.
- Add a Read the Docs post_checkout hook that exits 183 (the
  documented "cancel build successfully" code) for PR builds that
  don't touch docs/ or .readthedocs.yaml, mirroring the inverse on
  the RTD side.

Note: if any of the skipped checks are currently listed as required
in branch protection, doc-only PRs will block waiting for them. Flip
those to non-required, or add a matching no-op workflow that runs
under the ignored paths, as a follow-up.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .github/workflows/buf.yml           | 6 +++++-
 .github/workflows/ci-kotlin.yml     | 6 ++++++
 .github/workflows/ci-python.yml     | 6 ++++++
 .github/workflows/ci-typescript.yml | 6 ++++++
 .github/workflows/ci.yml            | 6 ++++++
 .readthedocs.yaml                   | 8 ++++++++
 6 files changed, 37 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/buf.yml b/.github/workflows/buf.yml
index fabfc40023..7ab73c4952 100644
--- a/.github/workflows/buf.yml
+++ b/.github/workflows/buf.yml
@@ -1,5 +1,9 @@
 name: buf
-on: pull_request
+on:
+  pull_request:
+    paths-ignore:
+      - 'docs/**'
+      - '.readthedocs.yaml'
 jobs:
   build:
     runs-on: ubuntu-latest
diff --git a/.github/workflows/ci-kotlin.yml b/.github/workflows/ci-kotlin.yml
index 8f67c6dc69..d791c7e727 100644
--- a/.github/workflows/ci-kotlin.yml
+++ b/.github/workflows/ci-kotlin.yml
@@ -3,7 +3,13 @@ on:
   push:
     branches:
       - main
+    paths-ignore:
+      - 'docs/**'
+      - '.readthedocs.yaml'
   pull_request:
+    paths-ignore:
+      - 'docs/**'
+      - '.readthedocs.yaml'
 jobs:
   build:
     if: false
diff --git a/.github/workflows/ci-python.yml b/.github/workflows/ci-python.yml
index a65315761d..9338a2304e 100644
--- a/.github/workflows/ci-python.yml
+++ b/.github/workflows/ci-python.yml
@@ -3,7 +3,13 @@ on:
   push:
     branches:
       - main
+    paths-ignore:
+      - 'docs/**'
+      - '.readthedocs.yaml'
   pull_request:
+    paths-ignore:
+      - 'docs/**'
+      - '.readthedocs.yaml'
 jobs:
   build:
     if: false
diff --git a/.github/workflows/ci-typescript.yml b/.github/workflows/ci-typescript.yml
index a6eccd09fb..5ce9b475e9 100644
--- a/.github/workflows/ci-typescript.yml
+++ b/.github/workflows/ci-typescript.yml
@@ -3,7 +3,13 @@ on:
   push:
     branches:
       - main
+    paths-ignore:
+      - 'docs/**'
+      - '.readthedocs.yaml'
   pull_request:
+    paths-ignore:
+      - 'docs/**'
+      - '.readthedocs.yaml'
 jobs:
   build:
     if: false
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 4cd48289a5..3e97d4c117 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -3,7 +3,13 @@ on:
   push:
     branches:
       - main
+    paths-ignore:
+      - 'docs/**'
+      - '.readthedocs.yaml'
   pull_request:
+    paths-ignore:
+      - 'docs/**'
+      - '.readthedocs.yaml'
 jobs:
   build:
     strategy:
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
index 9712e405d1..7895c313e4 100644
--- a/.readthedocs.yaml
+++ b/.readthedocs.yaml
@@ -10,6 +10,14 @@ build:
   os: ubuntu-22.04
   tools:
     python: "3.11"
+  jobs:
+    post_checkout:
+      # Cancel PR builds that don't touch the docs.
+      # https://docs.readthedocs.io/en/stable/build-customization.html#cancel-build-based-on-a-condition
+      - |
+        if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/main -- docs/ .readthedocs.yaml; then
+          exit 183
+        fi
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx: