ci: path-scope canvas on prs

.gitea/workflows/ci.yml

@@ -302,6 +302,7 @@ jobs:
   # siblings — verified empirically on PR #2314).
   canvas-build:
     name: Canvas (Next.js)
+    needs: changes
     runs-on: ubuntu-latest
     timeout-minutes: 20
     # Phase 4 (RFC #219 §1): confirmed green on main 2026-05-12.
@@ -310,20 +311,20 @@ jobs:
       run:
         working-directory: canvas
     steps:
-      - if: false
+      - if: ${{ github.event_name == 'pull_request' && needs.changes.outputs.canvas != 'true' }}
         working-directory: .
-        run: echo "No canvas/** changes — skipping real build steps; this job always runs to satisfy the required-check name on branch protection."
-      - if: always()
+        run: echo "No canvas/** changes on this PR — Canvas (Next.js) gate satisfied without running npm build/test."
+      - if: ${{ github.event_name != 'pull_request' || needs.changes.outputs.canvas == 'true' }}
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-      - if: always()
+      - if: ${{ github.event_name != 'pull_request' || needs.changes.outputs.canvas == 'true' }}
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
           node-version: '22'
-      - if: always()
+      - if: ${{ github.event_name != 'pull_request' || needs.changes.outputs.canvas == 'true' }}
         run: npm ci --include=optional --prefer-offline
-      - if: always()
+      - if: ${{ github.event_name != 'pull_request' || needs.changes.outputs.canvas == 'true' }}
         run: npm run build
-      - if: always()
+      - if: ${{ github.event_name != 'pull_request' || needs.changes.outputs.canvas == 'true' }}
         name: Run tests with coverage
         # Coverage instrumentation is configured in canvas/vitest.config.ts
         # (provider: v8, reporters: text + html + json-summary). Step 2 of
@@ -332,7 +333,7 @@ jobs:
         # tracked in #1815) after the team sees what current coverage is.
         run: npx vitest run --coverage
       - name: Upload coverage summary as artifact
-        if: always()
+        if: ${{ github.event_name != 'pull_request' || needs.changes.outputs.canvas == 'true' }}
         # Pinned to v3 for Gitea act_runner v0.6 compatibility — v4+ uses
         # the GHES 3.10+ artifact protocol that Gitea 1.22.x does NOT
         # implement, surfacing as `GHESNotSupportedError: @actions/artifact

tests/test_lint_workflow_yaml.py

@@ -713,3 +713,22 @@ def test_ci_platform_go_pr_steps_are_path_scoped():
         expr = step.get("if", "")
         assert "github.event_name != 'pull_request'" in expr
         assert "needs.changes.outputs.platform == 'true'" in expr
+
+
+def test_ci_canvas_nextjs_pr_steps_are_path_scoped():
+    doc = yaml.safe_load(CI_WORKFLOW.read_text(encoding="utf-8"))
+    canvas = doc["jobs"]["canvas-build"]
+    assert canvas.get("needs") == "changes"
+
+    expensive_steps = [
+        step
+        for step in canvas["steps"]
+        if step.get("uses")
+        or step.get("run", "").startswith("npm ")
+        or step.get("run", "").startswith("npx ")
+    ]
+    assert expensive_steps
+    for step in expensive_steps:
+        expr = step.get("if", "")
+        assert "github.event_name != 'pull_request'" in expr
+        assert "needs.changes.outputs.canvas == 'true'" in expr