ci: Gitea Actions pipeline + runner runbook (refs #30) (#37)

docs/runbooks/ci.md

@@ -0,0 +1,104 @@
+# CI runbook — Gitea Actions
+
+> **Status: no runner yet → run CI locally with `make ci`.** The workflow
+> `.gitea/workflows/ci.yaml` is in place, but the pipeline cannot go green until a
+> self-hosted `respellion-linux` runner is registered against the Gitea instance.
+> Until then, **`make ci` is the gate** — it runs the exact same checks locally
+> (the workflow calls the same `make` targets). Issue **#30 (S-00-c)** stays open
+> until CI is verified green on a runner.
+
+## The pipeline
+
+`.gitea/workflows/ci.yaml` runs on every push and pull request to `main`. Each job
+calls a `make` target — the **single source of truth** for the checks, so local
+and CI cannot drift:
+
+| Job | Target | Needs |
+|---|---|---|
+| `lint` | `make lint` → `dotnet format … --verify-no-changes` | .NET 10 SDK |
+| `build` | `make build` → `dotnet build … -c Release` | .NET 10 SDK |
+| `unit` | `make unit` → `dotnet test … -c Release` | .NET 10 SDK |
+| `compose-smoke` | `make smoke` → compose up `--wait` → `curl /health` → `down` | container engine + compose v2 |
+
+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.
+
+## Running CI locally (`make ci`)
+
+Until the runner exists, run the full pipeline yourself before pushing:
+
+```bash
+make ci          # lint + build + unit + smoke — what the pipeline runs
+make lint        # or a single stage
+make smoke       # compose up --wait, curl /health, tear down
+```
+
+**Prerequisites:** .NET 10 SDK, a container engine with Compose v2, and `curl`.
+
+On a **rootless Podman** box (the default dev setup here), the `smoke` target needs
+the Podman API socket and a Compose provider:
+
+```bash
+systemctl --user enable --now podman.socket            # start the API socket
+ln -sf "$(command -v podman)" ~/.local/bin/docker      # docker -> podman shim
+# install Docker Compose v2 into ~/.local/bin as `docker-compose` (the provider)
+```
+
+The Makefile auto-points `DOCKER_HOST` at `/run/user/$(id -u)/podman/podman.sock`
+when that socket exists and `DOCKER_HOST` is unset, so `make smoke` "just works"
+locally while leaving real Docker hosts / CI runners untouched.
+
+## Runner: `respellion-linux`
+
+The single self-hosted runner label this repo targets is **`respellion-linux`**
+(declared here per §15). It is intended to run **co-located on the Gitea server**
+(`git.labs.respellion.tech` / `46.224.220.37`) so CI is durable and independent of
+any developer machine.
+
+### Host prerequisites
+
+The runner executes jobs in **host mode** (see registration below), so the host
+must have, on `PATH`:
+
+- .NET 10 SDK (or let `setup-dotnet` install it into the runner tool cache)
+- A container engine with Compose v2 — Docker, or Podman with the Docker-compatible
+  socket and the `docker-compose` provider (as configured on the dev box)
+- `curl`
+
+### Install & register `act_runner` (on the Gitea server)
+
+```bash
+# 1. Install the binary (pick the version matching the Gitea release line)
+VER=0.2.11
+curl -fsSL -o /usr/local/bin/act_runner \
+  "https://dl.gitea.com/act_runner/${VER}/act_runner-${VER}-linux-amd64"
+chmod +x /usr/local/bin/act_runner
+
+# 2. Obtain a registration token from the Gitea UI:
+#    Site Administration → Actions → Runners → "Create new Runner"  (instance-level)
+#    (or Repo → Settings → Actions → Runners for a repo-scoped runner)
+
+# 3. Register with the respellion-linux label in HOST execution mode.
+#    The ":host" suffix means jobs run directly on the host shell, so
+#    `docker compose` in compose-smoke uses the host engine (no docker-in-docker).
+act_runner register --no-interactive \
+  --instance https://git.labs.respellion.tech \
+  --token <REGISTRATION_TOKEN> \
+  --name respellion-ci-1 \
+  --labels "respellion-linux:host"
+
+# 4. Run it (foreground to verify, then install as a systemd service)
+act_runner daemon
+```
+
+Verify in the Gitea UI (Actions → Runners) that `respellion-ci-1` shows **Idle**,
+then re-run the `CI` workflow; all four jobs should pass.
+
+## Security note
+
+A self-hosted runner in **host mode** executes workflow code directly on the Gitea
+server host. Anyone who can push a workflow can run code there. This is acceptable
+for a **private lab** instance with trusted contributors. For anything
+internet-facing, switch to container/VM isolation (`--labels "respellion-linux:docker://..."`)
+or a dedicated runner host, and gate workflow runs on approval for outside PRs.