register-referentie/docs/runbooks/ci.md

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:

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:

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)

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