tuning up runner improvements.

decisions/0014-docker-build-best-practices.md

@@ -110,8 +110,37 @@ RUN uv pip install --system \
 - Combine related commands into single RUN layers
 - Order from least to most frequently changing
 - Use multi-stage builds to reduce final image size
+- Use `COPY --link` for multi-stage `COPY --from` layers to make them independent
+  of prior layers, improving cache reuse when base images change:
 
-### 9. .dockerignore
+```dockerfile
+# --link makes this layer reusable even if the base image changes
+COPY --link --from=rocm-source /opt/rocm /opt/rocm
+```
+
+### 9. Registry-Based BuildKit Cache
+
+Use `type=registry` cache instead of `type=gha` (which only works on GitHub Actions).
+This stores build cache layers directly in the container registry with zstd compression:
+
+```yaml
+- name: Build and push
+  uses: docker/build-push-action@v5
+  with:
+    cache-from: type=registry,ref=${{ env.REGISTRY }}/image:buildcache
+    cache-to: type=registry,ref=${{ env.REGISTRY }}/image:buildcache,mode=max,image-manifest=true,compression=zstd
+```
+
+Benefits:
+- Works on any CI system (Gitea Actions, Jenkins, etc.)
+- `mode=max` caches all layers, not just final image layers
+- `compression=zstd` is faster than gzip with similar compression ratios
+- Cache survives runner restarts (stored in registry, not ephemeral disk)
+
+**Important:** `type=gha` is a no-op on self-hosted Gitea runners — it requires
+GitHub's cache API. Always use `type=registry` for self-hosted CI.
+
+### 10. .dockerignore
 
 All repos include a `.dockerignore`:
 
@@ -127,7 +156,7 @@ __pycache__/
 .ruff_cache/
 ```
 
-### 10. Makefile Integration
+### 11. Makefile Integration
 
 Standard targets for building and linting: