ci: gate the dev Docker build on image-affecting paths (#1143)

build-regular is a required status check that ran a full (several-minute)
Docker build on every PR, including docs/config-only PRs where the image is
byte-for-byte identical (#1134, surfaced merging #1129).

Add a paths-filter 'changes' job and gate build-regular's build steps on
'push to main OR image-affecting paths changed'. The job itself always runs,
so the required check always reports — avoiding the 'path-filtered required
check never reports -> merge deadlock' trap (a workflow-level paths filter
would have caused exactly that). Docs/config PRs now report build-regular
green in seconds; PRs touching Dockerfile/deps/app/frontend build as before.
Release build (build-and-release) is untouched.

Closes #1134

Author: lfnovo

.github/workflows/build-dev.yml

@@ -72,13 +72,51 @@ jobs:
             echo "This is a PR or manual run - test build only"
           fi
 
+  # Detect whether this PR touches anything that ends up in the Docker image.
+  # build-regular is a required status check, so it must always REPORT — the
+  # expensive build steps below are gated on this output instead of filtering
+  # the workflow trigger (a path-filtered required check never reports and
+  # deadlocks merge, even for admins). On push to main the build always runs.
+  changes:
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: read
+    outputs:
+      image: ${{ steps.filter.outputs.image }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Detect image-affecting changes
+        uses: dorny/paths-filter@v3
+        id: filter
+        with:
+          filters: |
+            image:
+              - 'Dockerfile*'
+              - 'pyproject.toml'
+              - 'uv.lock'
+              - 'open_notebook/**'
+              - 'api/**'
+              - 'commands/**'
+              - 'frontend/**'
+              - '.github/workflows/build-dev.yml'
+
+  # The job always runs (so the required `build-regular` check always reports),
+  # but every build step is gated on: push to main OR the PR touched an
+  # image-affecting path (needs.changes.outputs.image). Uses needs.* directly in
+  # each step `if:` (fully supported) rather than a job-level env indirection.
   build-regular:
-    needs: extract-version
+    needs: [extract-version, changes]
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
         uses: actions/checkout@v6
 
+      - name: Skip notice
+        if: needs.extract-version.outputs.is_push_to_main != 'true' && needs.changes.outputs.image != 'true'
+        run: echo "No image-affecting paths changed — skipping the Docker build. Reporting success."
+
       - name: Free up disk space
         if: needs.extract-version.outputs.is_push_to_main == 'true'
         run: |
@@ -90,6 +128,7 @@ jobs:
           df -h
 
       - name: Set up Docker Buildx
+        if: needs.extract-version.outputs.is_push_to_main == 'true' || needs.changes.outputs.image == 'true'
         uses: docker/setup-buildx-action@v4
 
       - name: Login to GitHub Container Registry
@@ -108,6 +147,7 @@ jobs:
           password: ${{ secrets.DOCKER_PASSWORD }}
 
       - name: Cache Docker layers
+        if: needs.extract-version.outputs.is_push_to_main == 'true' || needs.changes.outputs.image == 'true'
         uses: actions/cache@v5
         with:
           path: /tmp/.buildx-cache-dev
@@ -117,6 +157,7 @@ jobs:
 
       - name: Prepare Docker tags
         id: tags
+        if: needs.extract-version.outputs.is_push_to_main == 'true' || needs.changes.outputs.image == 'true'
         run: |
           if [[ "${{ needs.extract-version.outputs.is_push_to_main }}" == "true" ]]; then
             # Push to main: build and push v1-dev tags
@@ -135,6 +176,7 @@ jobs:
           fi
 
       - name: Build and push regular image
+        if: needs.extract-version.outputs.is_push_to_main == 'true' || needs.changes.outputs.image == 'true'
         uses: docker/build-push-action@v7
         with:
           context: .
@@ -147,6 +189,7 @@ jobs:
           cache-to: type=local,dest=/tmp/.buildx-cache-dev-new,mode=max
 
       - name: Move cache
+        if: needs.extract-version.outputs.is_push_to_main == 'true' || needs.changes.outputs.image == 'true'
         run: |
           rm -rf /tmp/.buildx-cache-dev
           mv /tmp/.buildx-cache-dev-new /tmp/.buildx-cache-dev