ci: add docker context guardrails for pre-commit and CI

Author: pRizz

.dockerignore

@@ -11,6 +11,8 @@ target
 # OS noise
 .DS_Store
 
-# Submodule checkout is not needed in Docker build context
-packages/opencode
+# Keep the submodule directory path available for Dockerfile COPY in remote mode,
+# but exclude all nested content from the default repo-root build context.
+# Local opencode dev builds use the custom context packer in
+# packages/core/src/docker/image.rs instead of .dockerignore.
 packages/opencode/**

.github/workflows/ci.yml

@@ -57,6 +57,23 @@ jobs:
       - name: Packer validate
         run: packer validate -var-file=infra/digitalocean/packer/variables.pkr.hcl infra/digitalocean/packer/opencode-marketplace.pkr.hcl
 
+  docker-context-guard:
+    name: Docker Context Guard
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Ensure opencode placeholder path exists for Docker context
+        run: mkdir -p packages/opencode
+
+      - name: Build Docker target stage
+        run: |
+          DOCKER_BUILDKIT=1 docker build \
+            --file packages/core/src/docker/Dockerfile \
+            --target opencode-build \
+            --tag opencode-cloud-sandbox:ci-check \
+            .
+
   # Build, lint, and test on multiple platforms
   # Clippy/build/test must run on each platform because #[cfg(target_os)] causes
   # different code to compile (e.g., systemd.rs on Linux, launchd.rs on macOS)

.github/workflows/docker-publish.yml

@@ -60,6 +60,9 @@ jobs:
           # when called via workflow_call, defaults to the commit that triggered the workflow
           ref: ${{ inputs.ref }}
 
+      - name: Ensure opencode placeholder path exists for Docker context
+        run: mkdir -p packages/opencode
+
       # NOTE: We parse the description label from the Dockerfile so the
       # multi-arch manifest annotation stays in sync and GHCR shows a description.
       # If you change the label format or quoting, update the extraction logic.

.github/workflows/dockerfile-updates.yml

@@ -20,6 +20,9 @@ jobs:
     steps:
       - uses: actions/checkout@v6
 
+      - name: Ensure opencode placeholder path exists for Docker context
+        run: mkdir -p packages/opencode
+
       - name: Install jq
         run: sudo apt-get update && sudo apt-get install -y jq
 

justfile

@@ -291,8 +291,15 @@ do-marketplace-build:
     packer build -var-file=infra/digitalocean/packer/variables.pkr.hcl \
         infra/digitalocean/packer/opencode-marketplace.pkr.hcl
 
-# Pre-commit checks (without Docker build - faster, works without Docker)
+# Pre-commit checks with conditional Docker stage build for Docker-risk changes.
+# This keeps routine commits fast while still catching Docker context regressions.
 pre-commit: check-opencode-submodule-published fmt lint build test-all-fast
+    @if ./scripts/should-run-docker-check.sh; then \
+        echo "Running Docker stage check because Docker-risk files changed..."; \
+        just check-docker; \
+    else \
+        echo "Skipping Docker stage check (no Docker-risk file changes)."; \
+    fi
 
 # Pre-commit checks including Docker build (requires Docker)
 pre-commit-full: check-opencode-submodule-published fmt lint build test-all-fast build-docker

packages/core/src/docker/Dockerfile

@@ -511,8 +511,10 @@ ARG OPENCODE_SOURCE=remote
 ARG OPENCODE_COMMIT
 ARG OPENCODE_LOCAL_REF
 
-# The custom build-context generator always adds packages/opencode. In remote mode
-# this is just a tiny placeholder; in local dev mode it contains the full submodule.
+# CLI builds use a custom build-context generator that always adds
+# packages/opencode. Repo-root Docker builds rely on checkout + .dockerignore to
+# keep this path as a tiny placeholder in remote mode.
+# In local dev mode it contains the full submodule.
 COPY --chown=opencoder:opencoder packages/opencode /tmp/opencode-local
 
 # Clone the fork and build opencode from source (as non-root user)

scripts/should-run-docker-check.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Decide whether local pre-commit should run the Docker stage check.
+# Exit 0 when Docker-risk files changed, otherwise exit 1.
+
+if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  echo "Not inside a git worktree; running Docker check."
+  exit 0
+fi
+
+changed_paths="$(
+  {
+    git diff --name-only
+    git diff --name-only --cached
+    git ls-files --others --exclude-standard
+  } | sed '/^$/d' | sort -u
+)"
+
+if [ -z "${changed_paths}" ]; then
+  echo "No file changes detected."
+  exit 1
+fi
+
+is_docker_risk_path() {
+  case "$1" in
+    .dockerignore) return 0 ;;
+    packages/core/src/docker/*) return 0 ;;
+    .github/workflows/ci.yml) return 0 ;;
+    .github/workflows/docker-publish.yml) return 0 ;;
+    .github/workflows/dockerfile-updates.yml) return 0 ;;
+    .github/workflows/version-bump.yml) return 0 ;;
+    scripts/check-dockerfile-updates.sh) return 0 ;;
+    scripts/extract-oci-description.py) return 0 ;;
+    scripts/should-run-docker-check.sh) return 0 ;;
+  esac
+  return 1
+}
+
+matched_paths=()
+while IFS= read -r path; do
+  [ -n "${path}" ] || continue
+  if is_docker_risk_path "${path}"; then
+    matched_paths+=("${path}")
+  fi
+done <<< "${changed_paths}"
+
+if [ "${#matched_paths[@]}" -eq 0 ]; then
+  echo "No Docker-risk file changes detected."
+  exit 1
+fi
+
+printf 'Docker-risk file changes detected:\n'
+printf '  - %s\n' "${matched_paths[@]}"
+exit 0