ci: drive pipeline via make targets + local make ci gate (refs #30)

Add a root Makefile (lint/build/unit/smoke/ci) as the single source of
truth for the checks, and have each Gitea Actions job call the matching
make target so local and CI cannot drift. `make ci` runs the full
pipeline locally — the interim gate while no runner is registered.

The smoke target auto-points DOCKER_HOST at the rootless Podman socket
when present (and DOCKER_HOST is unset), leaving Docker/CI hosts alone.
Document `make ci` and the Podman prerequisites in docs/runbooks/ci.md.

Verified: `make ci` is green locally (lint, build, unit, container smoke).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.gitea/workflows/ci.yaml

@@ -12,6 +12,9 @@ permissions:
 # Self-hosted runner — see docs/runbooks/ci.md for the runner setup.
 # `uses:` are absolute, tag-pinned URLs (CLAUDE.md §8.7 / §15).
 
+# Each job calls a `make` target — the same one developers run locally
+# (`make ci`). The Makefile is the single source of truth; see docs/runbooks/ci.md.
+
 jobs:
   lint:
     runs-on: respellion-linux
@@ -20,8 +23,7 @@ jobs:
       - uses: https://github.com/actions/setup-dotnet@v4
         with:
           dotnet-version: '10.0.x'
-      - name: dotnet format (verify, no changes)
+      - run: make lint
-        run: dotnet format services/bff/Bff.slnx --verify-no-changes
 
   build:
     runs-on: respellion-linux
@@ -30,7 +32,7 @@ jobs:
       - uses: https://github.com/actions/setup-dotnet@v4
         with:
           dotnet-version: '10.0.x'
-      - run: dotnet build services/bff/Bff.slnx -c Release
+      - run: make build
 
   unit:
     runs-on: respellion-linux
@@ -39,16 +41,10 @@ jobs:
       - uses: https://github.com/actions/setup-dotnet@v4
         with:
           dotnet-version: '10.0.x'
-      - run: dotnet test services/bff/Bff.slnx -c Release
+      - run: make unit
 
   compose-smoke:
     runs-on: respellion-linux
     steps:
       - uses: https://github.com/actions/checkout@v4
-      - name: compose up (wait for healthy)
+      - run: make smoke
-        run: docker compose -f infra/docker-compose.yml up -d --build --wait
-      - name: smoke test /health
-        run: curl -fsS http://localhost:8080/health
-      - name: compose down
-        if: always()
-        run: docker compose -f infra/docker-compose.yml down --volumes

Makefile

@@ -0,0 +1,50 @@
+# Developer + CI entrypoints.
+#
+# These targets are the single source of truth for the checks. The Gitea
+# Actions workflow (.gitea/workflows/ci.yaml) invokes the SAME targets, so
+# `make ci` locally runs exactly what the pipeline runs — no drift. Until a
+# self-hosted runner is registered, `make ci` is the gate (see docs/runbooks/ci.md).
+
+SLN        := services/bff/Bff.slnx
+COMPOSE    := infra/docker-compose.yml
+HEALTH_URL := http://localhost:8080/health
+
+# On a rootless Podman dev box, point Docker CLI/Compose at the Podman socket —
+# but only if that socket exists and DOCKER_HOST isn't already set, so real
+# Docker hosts and CI runners are left untouched.
+PODMAN_SOCK := /run/user/$(shell id -u)/podman/podman.sock
+ifeq ($(wildcard $(PODMAN_SOCK)),$(PODMAN_SOCK))
+ifeq ($(origin DOCKER_HOST),undefined)
+export DOCKER_HOST := unix://$(PODMAN_SOCK)
+endif
+endif
+
+.PHONY: ci lint build unit smoke down help
+
+## ci: run the full pipeline — lint, build, unit, smoke (mirrors Gitea Actions)
+ci: lint build unit smoke
+
+## lint: verify formatting (no changes)
+lint:
+	dotnet format $(SLN) --verify-no-changes
+
+## build: release build
+build:
+	dotnet build $(SLN) -c Release
+
+## unit: run unit tests
+unit:
+	dotnet test $(SLN) -c Release
+
+## smoke: compose up (wait for healthy), curl /health, then tear down
+smoke:
+	docker compose -f $(COMPOSE) up -d --build --wait
+	bash -c 'curl -fsS $(HEALTH_URL); rc=$$?; docker compose -f $(COMPOSE) down --volumes; exit $$rc'
+
+## down: stop and remove the local stack
+down:
+	docker compose -f $(COMPOSE) down --volumes
+
+## help: list available targets
+help:
+	@grep -E '^## ' $(MAKEFILE_LIST) | sed 's/^## //'

docs/runbooks/ci.md

@@ -1,26 +1,54 @@
 # CI runbook — Gitea Actions
 
-> **Status: pending runner.** The workflow `.gitea/workflows/ci.yaml` is in place,
+> **Status: no runner yet → run CI locally with `make ci`.** The workflow
-> but the pipeline cannot go green until a self-hosted runner with the
+> `.gitea/workflows/ci.yaml` is in place, but the pipeline cannot go green until a
-> `respellion-linux` label is registered against the Gitea instance. Until then
+> self-hosted `respellion-linux` runner is registered against the Gitea instance.
-> runs stay queued. Tracked by issue **#30 (S-00-c)**, which stays open until CI
+> Until then, **`make ci` is the gate** — it runs the exact same checks locally
-> is verified green.
+> (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`. Jobs:
+`.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 | Command | Needs |
+| Job | Target | Needs |
 |---|---|---|
-| `lint` | `dotnet format services/bff/Bff.slnx --verify-no-changes` | .NET 10 SDK |
+| `lint` | `make lint` → `dotnet format … --verify-no-changes` | .NET 10 SDK |
-| `build` | `dotnet build services/bff/Bff.slnx -c Release` | .NET 10 SDK |
+| `build` | `make build` → `dotnet build … -c Release` | .NET 10 SDK |
-| `unit` | `dotnet test services/bff/Bff.slnx -c Release` | .NET 10 SDK |
+| `unit` | `make unit` → `dotnet test … -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 |
+| `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`**