feat: add custom runner image support to ProjectSettings

Allow workspace admins to configure a custom runner container image
per project, with registry allowlist validation, pull secret support,
and feature flag gating across all layers.

Image selection precedence: ProjectSettings > agent registry > operator
default. Includes API input validation, gRPC presenter fields, frontend
settings UI with port/adapter pattern, conformance test suite, and
comprehensive imageref unit tests.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: quay-devel

.github/workflows/components-build-deploy.yml

@@ -121,6 +121,15 @@ jobs:
           username: ${{ secrets.REDHAT_USERNAME }}
           password: ${{ secrets.REDHAT_PASSWORD }}
 
+      - name: Read runner contract version
+        id: runner-version
+        run: |
+          if [ -f components/runners/ambient-runner/VERSION ]; then
+            echo "version=$(cat components/runners/ambient-runner/VERSION | tr -d '[:space:]')" >> "$GITHUB_OUTPUT"
+          else
+            echo "version=0.0.0" >> "$GITHUB_OUTPUT"
+          fi
+
       - name: Build and push ${{ matrix.component.name }} (${{ matrix.arch.suffix }})
         if: github.event_name != 'pull_request'
         uses: docker/build-push-action@v7
@@ -133,6 +142,7 @@ jobs:
           build-args: |
             AMBIENT_VERSION=${{ github.sha }}
             GIT_COMMIT=${{ github.sha }}
+            RUNNER_CONTRACT_VERSION=${{ steps.runner-version.outputs.version }}
           cache-from: type=gha,scope=${{ matrix.component.name }}-${{ matrix.arch.suffix }}
           cache-to: type=gha,mode=max,scope=${{ matrix.component.name }}-${{ matrix.arch.suffix }}
 
@@ -148,6 +158,7 @@ jobs:
           build-args: |
             AMBIENT_VERSION=${{ github.sha }}
             GIT_COMMIT=${{ github.sha }}
+            RUNNER_CONTRACT_VERSION=${{ steps.runner-version.outputs.version }}
           cache-from: type=gha,scope=${{ matrix.component.name }}-${{ matrix.arch.suffix }}
           cache-to: type=gha,mode=max,scope=${{ matrix.component.name }}-${{ matrix.arch.suffix }}
 

Makefile

@@ -194,6 +194,10 @@ build-runner: ## Build Claude Code runner image
 		-t $(RUNNER_IMAGE) .
 	@echo "$(COLOR_GREEN)✓$(COLOR_RESET) Runner built: $(RUNNER_IMAGE)"
 
+test-runner-conformance: ## Run conformance tests against runner image
+	@echo "$(COLOR_BLUE)▶$(COLOR_RESET) Running runner conformance tests against $(RUNNER_IMAGE)..."
+	@bash components/runners/conformance/run-conformance.sh $(RUNNER_IMAGE)
+
 build-state-sync: ## Build state-sync image for S3 persistence
 	@echo "$(COLOR_BLUE)▶$(COLOR_RESET) Building state-sync with $(CONTAINER_ENGINE)..."
 	@cd components/runners/state-sync && $(CONTAINER_ENGINE) build $(PLATFORM_FLAG) $(BUILD_FLAGS) \

components/ambient-api-server/openapi/openapi.projectSettings.yaml

@@ -221,6 +221,10 @@ components:
               type: string
             repositories:
               type: string
+            runner_image:
+              type: string
+            runner_image_pull_secret:
+              type: string
             created_at:
               type: string
               format: date-time
@@ -245,6 +249,10 @@ components:
           type: string
         repositories:
           type: string
+        runner_image:
+          type: string
+        runner_image_pull_secret:
+          type: string
   parameters:
       id:
         name: id