# CI runbook — Gitea Actions

> **Status: active.** The workflow `.gitea/workflows/ci.yaml` runs on Gitea's
> hosted `ubuntu-latest` runner — no self-hosted runner required.
> **`make ci` is still the local gate** — it runs the exact same checks
> (the workflow calls the same `make` targets).

## 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: `ubuntu-latest`

All jobs run on Gitea's hosted **`ubuntu-latest`** runner — no self-hosted runner
setup is required. The hosted runner ships with Docker and Docker Compose v2, so
`make smoke` (`docker compose … up --wait`) works without extra configuration.

If Gitea's hosted runners are unavailable and a self-hosted fallback is needed,
register an `act_runner` with the `ubuntu-latest` label:

```bash
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

act_runner register --no-interactive \
  --instance https://git.labs.respellion.tech \
  --token <REGISTRATION_TOKEN> \
  --name respellion-ci-1 \
  --labels "ubuntu-latest:docker://node:20-bookworm"

act_runner daemon
```