From 7b27c3a6c8b85835171ac5798938a1c406405fa5 Mon Sep 17 00:00:00 2001
From: Dimitri Fontaine <dim@tapoueh.org>
Date: Sun, 26 Jul 2026 19:12:58 +0200
Subject: [PATCH] ci: skip the build/test matrix on docs-only changes

main's branch protection requires specific job-name status checks
(Style check, pgaftest / *, pytest / *). A top-level push/pull_request
paths-ignore would make the whole workflow never run for a docs-only
commit, leaving those required checks permanently unreported and the PR
stuck -- GitHub only treats a *skipped* job as satisfying a required
check, not a workflow that never ran at all.

Add check_docs_only (same pattern as the existing check_base_changed
job) and gate style_checker and check_base_changed on it. Every other
job already transitively needs one of those two, and a job automatically
skips when any of its needs was skipped, so the whole matrix cascades to
skipped without extra per-job conditions.
---
 .github/workflows/ci.yml | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index de7622b98..afd22ec81 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -33,11 +33,42 @@ env:
   BASE: ghcr.io/hapostgres/pg_auto_failover/pgaf-base:bookworm
 
 jobs:
+  # ---------------------------------------------------------------------------
+  # 0. Detect a docs-only change (docs/**, *.md, LICENSE) so the expensive
+  #    build/test jobs below can skip themselves. A *skipped* job still
+  #    reports a "skipped" conclusion under its required-check name, which
+  #    branch protection treats as passing -- unlike a top-level
+  #    push/pull_request `paths-ignore`, which would make the workflow never
+  #    run at all and leave this repo's required status checks permanently
+  #    pending on a docs-only PR.
+  # ---------------------------------------------------------------------------
+  check_docs_only:
+    name: Check if this is a docs-only change
+    runs-on: ubuntu-latest
+    outputs:
+      docs_only: ${{ steps.diff.outputs.docs_only }}
+    steps:
+      - uses: actions/checkout@v7.0.0
+        with:
+          fetch-depth: 0
+
+      - name: Detect docs-only change
+        id: diff
+        run: |
+          BASE_REF="${{ github.event.pull_request.base.sha || 'HEAD~1' }}"
+          if git diff --name-only "${BASE_REF}"...HEAD | grep -qvE '^(docs/|.*\.md$|LICENSE$)'; then
+            echo "docs_only=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "docs_only=true"  >> "$GITHUB_OUTPUT"
+          fi
+
   # ---------------------------------------------------------------------------
   # 1. Style check
   # ---------------------------------------------------------------------------
   style_checker:
     name: Style check
+    needs: check_docs_only
+    if: needs.check_docs_only.outputs.docs_only != 'true'
     runs-on: ubuntu-latest
     container: citus/stylechecker:no-py
     steps:
@@ -58,6 +89,8 @@ jobs:
   # ---------------------------------------------------------------------------
   check_base_changed:
     name: Check if Dockerfile.base changed
+    needs: check_docs_only
+    if: needs.check_docs_only.outputs.docs_only != 'true'
     runs-on: ubuntu-latest
     outputs:
       changed: ${{ steps.diff.outputs.changed }}