# CI runbook — Gitea Actions

> **Status: pending runner.** The workflow `.gitea/workflows/ci.yaml` is in place,
> but the pipeline cannot go green until a self-hosted runner with the
> `respellion-linux` label is registered against the Gitea instance. Until then
> runs stay queued. Tracked by issue **#30 (S-00-c)**, which stays open until CI
> is verified green.

## The pipeline

`.gitea/workflows/ci.yaml` runs on every push and pull request to `main`. Jobs:

| Job | Command | Needs |
|---|---|---|
| `lint` | `dotnet format services/bff/Bff.slnx --verify-no-changes` | .NET 10 SDK |
| `build` | `dotnet build services/bff/Bff.slnx -c Release` | .NET 10 SDK |
| `unit` | `dotnet test services/bff/Bff.slnx -c Release` | .NET 10 SDK |
| `compose-smoke` | `docker compose -f infra/docker-compose.yml up -d --build --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.

## 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.