docs/ci.md

@@ -9,6 +9,24 @@ It runs `tests/run_tests.py` (full suite — unit + integration) on:
 Integration tests need Docker on the runner; they skip cleanly via
 `tests/_docker.skip_unless_docker` when no daemon is reachable.
 
+A small subset of integration tests skip when running specifically
+under Gitea Actions (`GITEA_ACTIONS=true`), because `act_runner` runs
+the job inside a container with the host's `/var/run/docker.sock`
+mounted in. That topology breaks two assumptions those tests make:
+
+- networks created via the host daemon aren't always visible to a
+  same-process `docker network ls` call from inside the job container,
+  and
+- ports published by sibling containers land on the host's loopback,
+  not on the job container's `127.0.0.1` — so HTTP probes against
+  `http://127.0.0.1:<host_port>` from inside the job time out.
+
+The affected tests (`test_orphan_cleanup.test_create_and_remove`,
+`test_pipelock_sidecar_smoke.test_smoke`) still run locally where the
+test process and Docker daemon share a host. Making them work in CI
+is a follow-up: either re-write them to discover container IPs via
+`docker inspect`, or reconfigure the runner with host networking.
+
 ## Branch protection on `main`
 
 Branch protection is **not** captured in tree — Gitea applies it via

tests/test_orphan_cleanup.py

@@ -36,6 +36,11 @@ class TestOrphanCleanup(unittest.TestCase):
         # Returning True == idempotent success.
         self.assertTrue(network_remove(f"claude-bottle-net-{self.slug}-does-not-exist"))
 
+    @unittest.skipIf(
+        os.environ.get("GITEA_ACTIONS") == "true",
+        "skipped under act_runner: docker socket mount topology breaks "
+        "in-process visibility of networks created on the host daemon",
+    )
     def test_create_and_remove(self):
         self.internal_name = network_create_internal(self.slug)
         self.egress_name = network_create_egress(self.slug)

tests/test_pipelock_sidecar_smoke.py

@@ -31,6 +31,11 @@ class TestPipelockSidecarSmoke(unittest.TestCase):
         )
         shutil.rmtree(self.work_dir, ignore_errors=True)
 
+    @unittest.skipIf(
+        os.environ.get("GITEA_ACTIONS") == "true",
+        "skipped under act_runner: published port is on the host's "
+        "loopback, not reachable from the job container's 127.0.0.1",
+    )
     def test_smoke(self):
         yaml_path = self.work_dir / "pipelock.yaml"
         pipelock_write_yaml(fixture_minimal(), "dev", yaml_path)