ci(acl): keep the integration lane local-only; document the runner gap (refs #46)

The hosted Gitea runner starts the OpenZaak stack as sibling containers via the
host daemon, so a process on the runner can't reach the published ports — the seed
and dotnet test get Connection refused on localhost:8000. Drop the (non-working)
integration CI job; make integration stays the local / host-runner gate. Document
the limitation in gitea-actions-gotchas.md §5 and the CI runbook, and track running
it inside the compose network in #55. ADR-0006 updated accordingly.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs/runbooks/ci.md

@@ -17,9 +17,14 @@ and CI cannot drift:
 | `build` | `make build` → `dotnet build … -c Release` | .NET 10 SDK |
 | `unit` | `make unit` → `dotnet test … -c Release --filter "Category!=Integration"` | .NET 10 SDK |
 | `mutation` | `make mutation` → `dotnet tool restore` → `dotnet stryker` (ACL); uploads the HTML report as an artifact | .NET 10 SDK |
-| `integration` | `make integration` → `openzaak-up` → seed a **published** BIG zaaktype (`OZ_PUBLISH=1`) → `dotnet test … --filter "Category=Integration"` → tear down | .NET 10 SDK + container engine + python3 + egress to `selectielijst.openzaak.nl` |
 | `compose-smoke` | `make smoke` → seed config volumes → `up -d` (full stack) → `up --wait` durable services → `down` | container engine + compose v2 |
 
+> **`make integration` is not a hosted-runner job yet.** The ACL ↔ real-OpenZaak
+> test (`make integration`, ADR-0006) passes locally and on a host-executing runner,
+> but a process on the hosted runner can't reach the stack's published ports
+> (sibling containers — see [gitea-actions-gotchas.md §5](gitea-actions-gotchas.md)).
+> Run it inside the compose network to gate it in CI — tracked in **#55**.
+
 All `uses:` references are absolute, tag-pinned URLs (`https://github.com/actions/checkout@v4`,
 `https://github.com/actions/setup-dotnet@v4`) per CLAUDE.md §8.7 and §15 — Gitea
 Actions resolves them from GitHub.

docs/runbooks/gitea-actions-gotchas.md

@@ -124,3 +124,34 @@ needed). v3 uses the older artifact protocol that Gitea implements, and has no G
 guard. Inputs are the same (`name`, `path`, `if-no-files-found`), so it is a drop-in
 swap. Do **not** bump to `@v4` until act_runner advertises github.com-compatible
 artifact support.
+
+---
+
+## 5. A runner process can't reach a service container's published port
+
+**Symptom** — green locally, but a CI step that runs *on the runner* and talks to a
+compose service over `localhost` fails. The ACL integration test's seed died with:
+
+```
+OpenZaak ready (000)
+urllib.error.URLError: <urlopen error [Errno 111] Connection refused>
+make: *** [Makefile:114: integration] Error 1
+```
+
+OpenZaak was demonstrably up — uwsgi had been serving for ~2 minutes — yet
+`curl`/`urllib` to `localhost:8000` from the runner were refused the whole time.
+
+**Why** — the same sibling-container split as §1. Compose starts the stack via the
+host daemon, so `ports: ["8000:8000"]` publishes to the *daemon host*, not to the job
+container. From the runner, `localhost:8000` has nothing listening. (`make smoke`
+sidesteps this by polling readiness via `docker inspect` (§2), never a service port.)
+
+**Fix** — don't talk to service ports from the runner. Either check state via `docker
+inspect` (health), or run the client **inside the compose network** so it reaches the
+service by name (`http://openzaak:8000`). For a test/seed that needs the repo's own
+code, deliver it via a **built image** (not a bind mount — §1), then
+`docker run --network <stack>_cg …`.
+
+**Status** — `make integration` (the ACL ↔ real-OpenZaak test, ADR-0006) therefore
+runs locally / on a host-executing runner only. Gating it on the hosted runner via
+the compose network is tracked in **#55**.