From d6a4f7c41fe27ddce256e830fcba8aecec101ce7 Mon Sep 17 00:00:00 2001
From: Haylan <code@arthurerlich.ch>
Date: Fri, 17 Jul 2026 12:37:12 +0200
Subject: [PATCH] feat(ci): update Gitea workflow to include registry login and
 cache handling adjustments

---
 .gitea/workflows/test.yml | 17 +++++++++++++++--
 CLAUDE.md                 | 17 +++++++++++++++++
 2 files changed, 32 insertions(+), 2 deletions(-)

diff --git a/.gitea/workflows/test.yml b/.gitea/workflows/test.yml
index c848f86..97e0e53 100644
--- a/.gitea/workflows/test.yml
+++ b/.gitea/workflows/test.yml
@@ -6,6 +6,9 @@ on:
   pull_request:
     branches: [main]
 
+env:
+  REGISTRY: git.arthurerlich.de
+
 jobs:
   build-dev:
     runs-on: ubuntu-latest
@@ -16,6 +19,16 @@ jobs:
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
 
+      # type=gha depends on act_runner's internal cache proxy, which is unreachable
+      # from job containers on this runner (dial tcp ... i/o timeout). Use the
+      # registry cache backend instead, same as docker-publish.yml.
+      - name: Log in to Gitea registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ gitea.actor }}
+          password: ${{ secrets.REGISTRY_TOKEN }}
+
       - name: Build dev image (PHP 8.4 + composer deps)
         uses: docker/build-push-action@v5
         with:
@@ -24,8 +37,8 @@ jobs:
           target: dev
           outputs: type=docker,dest=/tmp/graph-dev.tar
           tags: graph-dev:ci
-          cache-from: type=gha
-          cache-to: type=gha,mode=max
+          cache-from: type=registry,ref=${{ env.REGISTRY }}/${{ gitea.repository }}:buildcache-dev
+          cache-to: type=registry,ref=${{ env.REGISTRY }}/${{ gitea.repository }}:buildcache-dev,mode=max
 
       - name: Upload dev image
         uses: actions/upload-artifact@v4
diff --git a/CLAUDE.md b/CLAUDE.md
index d9384df..49dd6e4 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -138,12 +138,29 @@ Workflow files live in [.gitea/workflows/](.gitea/workflows/). This project uses
 - Secrets are set under Repository → Settings → Secrets → Actions
 - The registry hostname must be derived from `gitea.server_url` (strip the protocol prefix)
 - Triggers use standard `on:` syntax; `tags: '*.*.*'` matches semver pushes without a `v` prefix
+- Do not use `cache-from/cache-to: type=gha` — on this instance's act_runner (v2.0.0), the internal GitHub Actions-cache-compatible proxy is not reachable from job containers (`dial tcp <ip>:<port>: i/o timeout`), a known act_runner docker-executor networking limitation, not a workflow bug. Use `type=registry` instead (push cache blobs to `${{ env.REGISTRY }}/<repo>:buildcache*` — see both `test.yml` and `docker-publish.yml`); it requires a registry login step even for jobs that don't push the final image.
 
 **Current workflows:**
 
 | File                 | Trigger          | Purpose                                                   |
 | -------------------- | ---------------- | --------------------------------------------------------- |
 | `docker-publish.yml` | Push tag `*.*.*` | Build & push multi-arch image to Gitea container registry |
+| `test.yml`           | Push/PR to `main`| Build dev+prod images, run PHPUnit and PHPStan            |
+
+### Release testing with `act`
+
+Before tagging a release (anything that would trigger `docker-publish.yml`), run `test.yml` locally with [`act`](https://github.com/nektos/act) to catch pipeline failures before pushing. `test.yml` uses plain GitHub Actions syntax (no `gitea.*` contexts), so it runs under `act` unmodified.
+
+```bash
+act -j test \
+  -P ubuntu-latest=catthehacker/ubuntu:act-latest \
+  --artifact-server-path /tmp/act-artifacts
+```
+
+- `-P ubuntu-latest=catthehacker/ubuntu:act-latest` — default act runner image lacks a Docker CLI, which the `test` job needs for its nested `docker run` steps
+- `--artifact-server-path` — required for the `upload-artifact`/`download-artifact` steps to work; without it they silently no-op
+
+**If `act` is not installed:** warn the user it's missing and how to install it (`sudo pacman -S act`, or see the repo above) — do not install it yourself or force the check. `docker-publish.yml` is out of scope for `act` (it needs real `gitea.*` context and a live registry secret); don't try to run it locally.
 
 ## Docker