From a0fe8acb9c1cdaac694232364582809927e0f701 Mon Sep 17 00:00:00 2001
From: ak2k <19240940+ak2k@users.noreply.github.com>
Date: Wed, 27 May 2026 18:56:33 -0400
Subject: [PATCH] ci: report required check contexts on docs-only changes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The check workflow was path-filtered to code files (**.nix, flake.lock,
workflows, pyproject.toml, *.py), so docs-only PRs never triggered it.
Branch protection requires the three check (<os>) contexts, so those PRs
were permanently BLOCKED — only an admin enforce_admins toggle could land
a README change.

Drop the path filter and gate the expensive build behind a changes job
(dorny/paths-filter). The check (<os>) matrix now always runs and always
reports its contexts: real nix flake check when code changed, an instant
pass when the change is docs-only. Branch protection is unchanged (same
context names, enforce_admins/strict stay on), and docs PRs become
mergeable — including via auto-merge, which is already enabled on the repo.

Gating in one workflow (rather than a second no-op workflow on
paths-ignore) avoids a masking window on mixed code+docs PRs, where an
instant green could let a still-running real build be merged.
---
 .github/workflows/check.yml | 47 +++++++++++++++++++++++++++----------
 1 file changed, 35 insertions(+), 12 deletions(-)

diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml
index 0ee6d0a..55aa805 100644
--- a/.github/workflows/check.yml
+++ b/.github/workflows/check.yml
@@ -3,20 +3,8 @@ name: Check
 on:
   push:
     branches: [main]
-    paths:
-      - '**.nix'
-      - 'flake.lock'
-      - '.github/workflows/**'
-      - '**/pyproject.toml'
-      - '**/*.py'
   pull_request:
     branches: [main]
-    paths:
-      - '**.nix'
-      - 'flake.lock'
-      - '.github/workflows/**'
-      - '**/pyproject.toml'
-      - '**/*.py'
   workflow_dispatch:
 
 concurrency:
@@ -27,8 +15,35 @@ permissions:
   contents: read
 
 jobs:
+  # Decide whether the change touches anything `nix flake check` cares about.
+  # The `check (<os>)` matrix below always runs and always reports its status
+  # contexts (which branch protection requires), but only does the expensive
+  # build when code changed. Docs-only changes (e.g. README) report green
+  # without building. Without this gate the workflow was path-filtered, so it
+  # never reported the required contexts on docs-only PRs — leaving them
+  # permanently blocked from merging.
+  changes:
+    runs-on: ubuntu-latest
+    outputs:
+      code: ${{ steps.filter.outputs.code }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - uses: dorny/paths-filter@v3
+        id: filter
+        with:
+          filters: |
+            code:
+              - '**.nix'
+              - 'flake.lock'
+              - '.github/workflows/**'
+              - '**/pyproject.toml'
+              - '**/*.py'
+
   check:
     name: check (${{ matrix.os }})
+    needs: changes
     runs-on: ${{ matrix.os }}
     timeout-minutes: 30
     strategy:
@@ -43,17 +58,25 @@ jobs:
           # in the 24h queue), and nixpkgs is sunsetting x86_64-darwin after
           # 25.11. macos-14 covers the live darwin target.
     steps:
+      - name: Docs-only change — nix flake check not required
+        if: needs.changes.outputs.code != 'true'
+        run: echo "No code files changed; skipping nix flake check for this context."
+
       - uses: actions/checkout@v6
+        if: needs.changes.outputs.code == 'true'
 
       - uses: cachix/install-nix-action@v31
+        if: needs.changes.outputs.code == 'true'
         with:
           extra_nix_config: |
             access-tokens = github.com=${{ secrets.GITHUB_TOKEN }}
 
       - uses: cachix/cachix-action@v17
+        if: needs.changes.outputs.code == 'true'
         with:
           name: ak2k
           authToken: ${{ secrets.CACHIX_AUTH_TOKEN }}
 
       - name: Flake check (builds + pushes all packages)
+        if: needs.changes.outputs.code == 'true'
         run: nix flake check -L