From f06005ef27fa2ddd955ff1d330557986c4eabd35 Mon Sep 17 00:00:00 2001
From: Devin Foley <devin@paperclip.ing>
Date: Thu, 10 Sep 2026 19:23:05 -0700
Subject: [PATCH] ci: compile the isolated Docker Runner target in pull
 requests

Co-Authored-By: Paperclip <noreply@paperclip.ing>
---
 .github/workflows/docker-runner-check.yml | 37 ++++++++++++++++++++++
 doc/DOCKER.md                             | 38 +++++++++++++----------
 2 files changed, 59 insertions(+), 16 deletions(-)
 create mode 100644 .github/workflows/docker-runner-check.yml

diff --git a/.github/workflows/docker-runner-check.yml b/.github/workflows/docker-runner-check.yml
new file mode 100644
index 0000000000..e9705c3b5e
--- /dev/null
+++ b/.github/workflows/docker-runner-check.yml
@@ -0,0 +1,37 @@
+name: Docker Runner check
+
+on:
+  pull_request:
+    paths:
+      - .github/workflows/docker-runner-check.yml
+      - Dockerfile
+      - .dockerignore
+      - packages/paperclip-runner/rust-toolchain.toml
+      - packages/paperclip-runner/runner/**
+      - packages/paperclip-runner/protocol/**
+
+permissions: {}
+
+concurrency:
+  group: docker-runner-check-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  runner:
+    name: Compile isolated native Runner
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4
+      # Compile the real target with the real .dockerignore. This catches new
+      # Cargo or embedded protocol inputs that the isolated COPY set omits.
+      # No registry credentials, cache imports/exports, or image publication.
+      - name: Compile the Runner from its isolated Docker context
+        run: docker buildx build --target runner-build --progress plain .
diff --git a/doc/DOCKER.md b/doc/DOCKER.md
index 2c701988c2..972ecfb32e 100644
--- a/doc/DOCKER.md
+++ b/doc/DOCKER.md
@@ -32,22 +32,6 @@ docker build -t paperclip-local \
   --build-arg USER_UID=$(id -u) --build-arg USER_GID=$(id -g) .
 ```
 
-## Native Runner build cache
-
-The image compiles the native Runner in `runner-build`, before copying the
-application source. That stage includes the pinned Rust compiler, the complete
-Cargo workspace and lockfile, and the protocol schemas and fixtures embedded
-by Rust. Changes to those inputs rebuild the native binary. Ordinary server or
-UI changes can reuse it through the existing registry cache (`mode=max`). Each
-platform gets its own native build; no cross-architecture binary is reused.
-
-The application build inherits that stage and still runs the normal server
-build, including Cargo, binary staging, and generated-contract checks. Rust
-input file times are normalized in both stages so fresh checkouts do not force
-Cargo to rebuild unchanged source. Changes made by build scripts still reach
-Cargo's normal validation. The final application copy excludes Cargo's target
-directory as before. Cache misses only cost compilation time.
-
 ## One-liner (build + run)
 
 ```sh
@@ -319,3 +303,25 @@ Notes:
 
 - The `docker-entrypoint.sh` adjusts the container `node` user UID/GID at startup to match the values passed via `USER_UID`/`USER_GID`, avoiding permission issues on bind-mounted volumes.
 - Paperclip data persists via Docker volumes/bind mounts (compose) or at `~/.local/share/paperclip` (quadlet).
+
+## Native Runner build cache
+
+The image compiles the native Runner in `runner-build`, before copying the
+application source. That stage includes the pinned Rust compiler, the complete
+Cargo workspace and lockfile, and the protocol schemas and fixtures embedded
+by Rust. Changes to those inputs rebuild the native binary. Ordinary server or
+UI changes can reuse it through the existing registry cache (`mode=max`). Each
+platform gets its own native build; no cross-architecture binary is reused.
+
+The application build inherits that stage and still runs the normal server
+build, including Cargo, binary staging, and generated-contract checks. Rust
+input file times are normalized in both stages so fresh checkouts do not force
+Cargo to rebuild unchanged source. Changes made by build scripts still reach
+Cargo's normal validation. The final application copy excludes Cargo's target
+directory as before. Cache misses only cost compilation time.
+
+Pull requests that change the Dockerfile, Docker ignore rules, or Runner native
+inputs also build the isolated `runner-build` target in `Docker Runner check`.
+This compiles against the actual reduced context and catches missing embedded
+inputs before the post-merge image build. It uses a GitHub-hosted runner with
+read-only repository access and does not publish images or cache artifacts.