ci: Add "PR checks" gate job to enable auto-merge (#2336)

Author: schloerke

.claude/references/commit-conventions.md

@@ -44,11 +44,15 @@ merged, so the PR title becomes the commit message on `main`):
 
 ## Merging PRs
 
-- When instructed to merge a PR, **squash merge** (`gh pr merge <number> --squash`)
-  only after the **full test suite (150+ GHA jobs) has succeeded** (`gh pr checks`).
-- **Never use `gh pr merge --auto`**: this repo has no required checks, so
-  `--auto` merges instantly instead of waiting for CI. Watch CI to completion,
-  then merge.
+- When instructed to merge a PR, **squash merge with auto-merge**
+  (`gh pr merge <number> --squash --auto`). Branch protection requires the
+  **"PR checks"** status check — the `pr-gate` job in
+  `.github/workflows/pytest.yaml` that fans in every PR job — so `--auto`
+  waits for the full test suite before merging.
+- The gate skips on draft PRs (drafts run a reduced test matrix and cannot be
+  merged anyway); mark the PR ready for review to trigger the full matrix.
+- When adding a job to `pytest.yaml`, add it to the `pr-gate` job's `needs:`
+  list, or its failures will not block merging.
 
 ## Handling flaky test failures in CI
 

.github/workflows/build-docs.yaml

@@ -20,10 +20,8 @@ on:
 jobs:
   build-docs:
     runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        python-version: ["3.13"]
-      fail-fast: false
+    env:
+      PYTHON_VERSION: "3.13"
 
     steps:
       - uses: actions/checkout@v6
@@ -33,7 +31,7 @@ jobs:
       - name: Setup py-shiny
         uses: ./.github/py-shiny/setup
         with:
-          python-version: ${{ matrix.python-version }}
+          python-version: ${{ env.PYTHON_VERSION }}
 
       # =====================================================
       # API docs

.github/workflows/pytest.yaml

@@ -326,3 +326,33 @@ jobs:
         uses: ./.github/py-shiny/narwhals-test
         with:
           shiny-dir: "."
+
+  # Single stable check for branch protection / auto-merge. Jobs above may be
+  # renamed or re-matrixed freely, but every PR job MUST be listed in `needs`
+  # below or its failure will not block merging.
+  pr-gate:
+    name: "PR checks"
+    # `always()` is required: without it, an upstream failure would make this
+    # job skip, and GitHub treats a skipped required check as satisfied.
+    # Skipping on draft PRs is safe for the same reason in reverse: drafts
+    # cannot be merged (or auto-merged) regardless, and skipping avoids
+    # failure emails from the reduced draft test matrix. Marking the PR
+    # ready for review re-triggers the workflow with the full matrix.
+    if: always() && github.event_name == 'pull_request' && !github.event.pull_request.draft
+    needs:
+      - check
+      - playwright-shiny
+      - playwright-examples
+      - playwright-ai
+      - playwright-deploys-precheck
+      - test-narwhals-integration
+    runs-on: ubuntu-latest
+    steps:
+      - name: Verify that all PR jobs succeeded
+        env:
+          RESULTS: ${{ toJSON(needs.*.result) }}
+        run: |
+          echo "Job results: $RESULTS"
+          if echo "$RESULTS" | grep -qE 'failure|cancelled|skipped'; then
+            exit 1
+          fi