CI: paths-ignore + required matrix checks leaves wheels/docs-only PRs stuck pending forever

[jhelferty-nv]

Summary

PRs that only change files listed in ci.yml's paths-ignore never trigger the ci workflow, but branch protection on main still requires all 12 build (...) matrix status checks. GitHub shows those checks as "Expected — Waiting for status to be reported" indefinitely, blocking merge even when other checks (pre-commit, license/cla) pass.

Current example

• Blocked PR: wheels: add Python 3.14 support #1002 (adds Python 3.14 wheel support; only edits .github/workflows/wheels.yml)
• Related user-facing issue: pip install from python 3.14 installs only v0.23.0 #950 (pip install on Python 3.14 falls back to v0.23.0)

Root cause

ci.yml uses workflow-level paths-ignore to skip the full build matrix for certain path-only changes:

pull_request:
  paths-ignore:
    - "LICENSES/**"
    - "LICENSE"
    - "**.md"
    - .github/workflows/wheels.yml
    - .github/workflows/ci-gcp.yml
    - .github/workflows/ci-latest-slang.yml

When a PR touches only ignored paths, the ci workflow does not run at all. Branch protection still requires these 12 contexts (among others):

• build (linux, x86_64, gcc, Debug, 3.10) … through … build (windows, x86_64, msvc, Release, 3.10)
• license/cla

A workflow skipped by paths-ignore never reports status → required checks stay pending forever. This is different from a job skipped via if: (which GitHub treats as passing).

Note: the wheels workflow is workflow_dispatch-only, so PR CI does not validate wheel matrix changes either.

History

When	What
Apr 2025	paths-ignore added to ci.yml for docs/**, LICENSE*, **.md (Simon Kallweit)
May 2025	#175 added .github/workflows/wheels.yml to paths-ignore when macOS wheel builds were introduced
Mar 2026	#847 opened (Report passing CI status when path filter skips builds) — proposed replacing workflow-level paths-ignore with a filter job that gates the build matrix via if:, so skipped builds report as skipped rather than missing (same pattern as the shader-slang/slang repo's filter + check-ci gate). Iterated to a bash/git diff approach after feedback from Chris Cummings on third-party action dependencies.
Mar 12, 2026	#847 closed without merging, with a note to "remove the filtering altogether" — that follow-up was never implemented; paths-ignore remains in place.
Jul 15, 2026	Recurrence on #1002; comment added to closed #847.

There is no open tracking issue for the #847 closure decision.

Prior art (slang repo)

The shader-slang/slang repo solves this with:

1. A filter job that detects docs-only changes
2. Build jobs gated with if: should-run == 'true' (skipped jobs count as passing)
3. A single check-ci aggregate gate job as the only required status check

SlangPy still lists all 12 matrix job names individually in branch protection and uses workflow-level paths-ignore instead.

Proposed fixes

Option A — Filter + aggregate gate (revive #847, align with slang):

• Remove paths-ignore from the pull_request trigger (workflow always runs)
• Add filter + ci gate jobs; gate build with if:
• Update branch protection to require ci + license/cla instead of 12 matrix names

Option B — Remove filtering (alternative from #847 closure):

• Drop paths-ignore entirely; always run the full matrix on every PR
• Simplest, but higher CI cost on docs/wheels-only changes

Workarounds (today)

• Add a trivial change to a non-ignored file to force ci to run
• Admin merge bypassing required checks
• Manual wheels workflow build-only run (validates wheels but does not unblock branch protection)

Acceptance criteria

• PRs that only change wheels.yml (or other ignored paths) can merge without stuck pending checks
• Full ci matrix still runs and gates merges for real code changes
• No recurrence of the Report passing CI status when path filter skips builds #847 / wheels: add Python 3.14 support #1002 failure mode

[nv-slang-bot]

Triage — CI infrastructure / branch-protection deadlock (updated: design verified, holding for maintainer decision)

• Status: Triaged and design-verified against origin/main. A ready-to-apply patch is drafted (Approach C). Held pending a maintainer A/B/C decision — no bot-landable PR results, so this comment is the observability footprint.
• Link: Recurrence PR wheels: add Python 3.14 support #1002 (Py 3.14 wheels); downstream user impact pip install from python 3.14 installs only v0.23.0 #950; prior abandoned fix Report passing CI status when path filter skips builds #847 (closed 2026‑03‑12, "remove the filtering altogether as discussed offline" — never implemented). Report passing CI status when path filter skips builds #847's diff was recovered (refs/pull/847/head @ 337b4a1): a filter job + if:‑gate, no aggregate gate.
• Verdict: Root cause confirmed — trigger‑level paths-ignore (ci.yml:7-14 push, :17-23 PR) means an ignored‑path‑only change never runs the workflow, so the 12 required build (...) contexts sit "Expected — Waiting for status" forever. A job‑level if: skip instead reports each context as skipped = passing. Three viable fixes: (C, issue's Option B) delete both paths-ignore blocks — ~15‑line deletion, lowest risk, matches the documented offline decision, higher CI cost; (A) graft Report passing CI status when path filter skips builds #847's filter job + if:‑gate onto the current matrix, keep the 12 required names — preserves cost savings, keeps brittle names (note: cannot verbatim‑revive Report passing CI status when path filter skips builds #847 — its runner labels are stale); (B, issue's Option A) full alignment with shader-slang/slang (filter → if:‑gated jobs → single aggregate gate as the only required check) — most robust, needs a branch‑protection swap. The aggregate idiom already exists internally at ci-latest-slang.yml:113-147.
• Next-action: Maintainer decision needed on A / B / C. On a pick, the exact diff is prepared as a patch/draft‑PR artifact for a maintainer to apply. Recommended default: C.
• Blocker: Landing requires a maintainer regardless of design — this bot cannot push .github/workflows/** (no workflows permission; cross‑fork workflow PRs are policy‑closed). If A or B is chosen, the branch‑protection required‑checks change is an admin‑only repo‑settings action (bot cannot read the protection API), sequenced after the YAML lands.

_{🤖 Generated by an automated SlangPy coworker — may be inaccurate. A human maintainer should verify.}