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

@@ -0,0 +1,50 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+# 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
+    steps:
+      - uses: https://github.com/actions/checkout@v4
+      - uses: https://github.com/actions/setup-dotnet@v4
+        with:
+          dotnet-version: '10.0.x'
+      - run: make lint
+
+  build:
+    runs-on: respellion-linux
+    steps:
+      - uses: https://github.com/actions/checkout@v4
+      - uses: https://github.com/actions/setup-dotnet@v4
+        with:
+          dotnet-version: '10.0.x'
+      - run: make build
+
+  unit:
+    runs-on: respellion-linux
+    steps:
+      - uses: https://github.com/actions/checkout@v4
+      - uses: https://github.com/actions/setup-dotnet@v4
+        with:
+          dotnet-version: '10.0.x'
+      - run: make unit
+
+  compose-smoke:
+    runs-on: respellion-linux
+    steps:
+      - uses: https://github.com/actions/checkout@v4
+      - run: make smoke

.gitignore

@@ -0,0 +1,27 @@
+# .NET build output
+bin/
+obj/
+[Dd]ebug/
+[Rr]elease/
+*.user
+
+# Test results / coverage
+[Tt]est[Rr]esults/
+*.trx
+coverage*.json
+coverage*.xml
+*.coverage
+
+# Rider / VS / VS Code
+.idea/
+.vs/
+.vscode/
+
+# Node / Angular (added as the frontend lands)
+node_modules/
+dist/
+.angular/
+
+# OS
+.DS_Store
+Thumbs.db

BACKLOG.md

@@ -12,22 +12,41 @@ Each slice is **independently demoable** and meets the Definition of Done in `CL
 
 ## Iteration 0 — Foundations *(milestone: `Iteration 0 — Foundations`)*
 
-### S-00 · Repository skeleton, Gitea Actions CI, contributor workflow
+> **S-00 was split** (CLAUDE.md §13) into the sub-slices below. The original
+> outcome — a fresh clone + `docker compose up` reaching a green BFF health
+> endpoint, with CI green and the contributor scaffolding in place — is the sum
+> of S-00-a…e. The Gitea milestones, labels, and slice issues already exist —
+> they are managed directly with the `tea` CLI.
 
-**Outcome:** A fresh `git clone` from the Respellion Gitea remote, followed by `docker compose up`, produces a green "hello world" health endpoint from a placeholder BFF. Gitea Actions runs lint, build, unit tests, and the compose-up smoke test, all green. Issue templates, PR template, milestones, labels, and the first project board exist in Gitea.
+### S-00-a · Placeholder BFF + health endpoint
 
-**Acceptance:**
+**Outcome:** A minimal .NET BFF exposing `GET /health` returning green; runnable with `dotnet run`. TDD anchor for the slice.
 
-- New developer follows `README.md` and reaches a green local environment in under 10 minutes.
+**Touches:** `services/bff/`, tests. **Out of scope:** Docker, CI, OIDC.
-- Gitea Actions pipeline green on `main`.
-- `git-cliff` produces an empty `CHANGELOG.md`.
-- `docs/PRD.md`, `CLAUDE.md`, `BACKLOG.md`, `docs/architecture/adr-0001-loose-coupling.md`, `docs/gitea-workflow.md` all in repo.
-- `.gitea/workflows/ci.yaml`, `.gitea/ISSUE_TEMPLATE/{slice,bug,adr-proposal}.md`, `.gitea/PULL_REQUEST_TEMPLATE.md` all in repo.
-- Gitea milestone `Iteration 1 — Walking Skeleton` exists, populated with issues S-01 through S-09.
 
-**Touches:** repo layout, Gitea Actions workflows, Dockerfile for placeholder BFF, `docker-compose.yml` skeleton, MkDocs scaffold, Gitea issue/PR templates.
+### S-00-b · Dockerfile + compose skeleton + compose-up smoke
 
-**Out of scope:** any business logic, frontend, OpenZaak.
+**Outcome:** BFF containerized; `infra/docker-compose.yml` brings it up; health green within 3 minutes from a fresh clone.
+
+**Touches:** `services/bff/Dockerfile`, `infra/docker-compose.yml`, smoke script. **Out of scope:** other services, CI.
+
+### S-00-c · Gitea Actions CI (lint, build, unit, compose-up smoke)
+
+**Outcome:** `.gitea/workflows/ci.yaml` green on PRs and `main`: lint, build, unit, compose-up smoke. Actions pinned by absolute URL (§8.7/§15).
+
+**Touches:** `.gitea/workflows/ci.yaml`, `docs/runbooks/ci.md`. **Out of scope:** mutation, e2e, container push.
+
+### S-00-d · Contributor workflow: issue/PR templates, git-cliff, CHANGELOG
+
+**Outcome:** Issue templates (`slice`/`bug`/`adr-proposal`), PR template, `git-cliff` → empty `CHANGELOG.md`, `docs/gitea-workflow.md`.
+
+**Touches:** `.gitea/ISSUE_TEMPLATE/`, `.gitea/PULL_REQUEST_TEMPLATE.md`, `cliff.toml`, `CHANGELOG.md`, `docs/gitea-workflow.md`. **Out of scope:** app code.
+
+### S-00-e · Docs scaffold: MkDocs + ADR-0001 + README quickstart
+
+**Outcome:** MkDocs builds the `docs/` site; `docs/architecture/adr-0001-loose-coupling.md` exists; README has a sub-10-minute quickstart.
+
+**Touches:** `mkdocs.yml`, `docs/` nav, `docs/architecture/adr-0001-loose-coupling.md`, `README.md`. **Out of scope:** Gitea Pages publish.
 
 ---
 

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/^## //'

README.md

@@ -56,6 +56,15 @@ docker compose -f infra/docker-compose.yml up -d
 
 Health checks should be green within ~3 minutes on a developer machine. If something fails, see [docs/runbooks/local-startup.md](docs/runbooks/local-startup.md).
 
+> **Wired today (Iteration 0):** only the placeholder BFF is in `infra/docker-compose.yml` so far. Bring it up and smoke-test its health endpoint:
+>
+> ```bash
+> docker compose -f infra/docker-compose.yml up -d --build --wait
+> curl http://localhost:8080/health   # -> Healthy
+> ```
+>
+> `--wait` exits non-zero unless the container reports healthy, so this doubles as the compose-up smoke test. The remaining services and the URLs below land in later slices.
+
 **Default URLs**
 
 | Service | URL |

docs/PRD.md

@@ -85,7 +85,7 @@ The five flows form the BDD acceptance backbone (Gherkin scenarios in `tests/acc
 
 - **Source control & collaboration:** **Gitea** (Respellion self-hosted) — repository, issues, milestones, labels, projects, releases, container registry, wiki, packages.
 - **CI/CD:** **Gitea Actions** running on Respellion-hosted `act_runner` instances. Workflow files live in `.gitea/workflows/`. Marketplace actions are referenced via absolute URLs (`uses: https://github.com/actions/checkout@v4` or Gitea-hosted equivalents where available) for reproducibility.
-- **Backend:** .NET 9 (LTS at iteration time), C#, minimal APIs for BFF, MediatR for in-process messaging within Domain Service, EF Core for the projection store and domain DB.
+- **Backend:** .NET 10 (LTS at iteration time), C#, minimal APIs for BFF, MediatR for in-process messaging within Domain Service, EF Core for the projection store and domain DB.
 - **Frontend:** Angular (latest LTS) + TypeScript, standalone components + signals, Nx monorepo, NL Design System component library, Angular Testing Library + Playwright.
 - **Workflow:** Flowable (BPMN + DMN) via Docker image; Postgres for engine store.
 - **Identity:** Keycloak with pre-seeded realms.

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.

global.json

@@ -0,0 +1,6 @@
+{
+  "sdk": {
+    "version": "10.0.203",
+    "rollForward": "latestFeature"
+  }
+}

infra/docker-compose.yml

@@ -0,0 +1,19 @@
+# Local development stack. Grows service-by-service with each slice.
+# S-00-b: the placeholder BFF with a /health check.
+#
+#   docker compose -f infra/docker-compose.yml up -d --build --wait
+#   curl http://localhost:8080/health   # -> Healthy
+services:
+  bff:
+    build:
+      context: ../services/bff
+      dockerfile: Dockerfile
+    image: register-referentie/bff:dev
+    ports:
+      - "8080:8080"
+    healthcheck:
+      test: ["CMD", "curl", "-fsS", "http://localhost:8080/health"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+      start_period: 10s

services/bff/.dockerignore

@@ -0,0 +1,3 @@
+**/bin
+**/obj
+**/*.user

services/bff/Bff.Api/Bff.Api.csproj

@@ -0,0 +1,9 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+</Project>

services/bff/Bff.Api/Program.cs

@@ -0,0 +1,12 @@
+var builder = WebApplication.CreateBuilder(args);
+builder.Services.AddHealthChecks();
+
+var app = builder.Build();
+
+app.MapGet("/", () => "BFF placeholder");
+app.MapHealthChecks("/health");
+
+app.Run();
+
+// Exposed so the test host (WebApplicationFactory<Program>) can boot the app.
+public partial class Program;

services/bff/Bff.Api/Properties/launchSettings.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json.schemastore.org/launchsettings.json",
+  "profiles": {
+    "http": {
+      "commandName": "Project",
+      "dotnetRunMessages": true,
+      "launchBrowser": true,
+      "applicationUrl": "http://localhost:5249",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development"
+      }
+    },
+    "https": {
+      "commandName": "Project",
+      "dotnetRunMessages": true,
+      "launchBrowser": true,
+      "applicationUrl": "https://localhost:7106;http://localhost:5249",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development"
+      }
+    }
+  }
+}

services/bff/Bff.Api/appsettings.Development.json

@@ -0,0 +1,8 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning"
+    }
+  }
+}

services/bff/Bff.Api/appsettings.json

@@ -0,0 +1,9 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning"
+    }
+  },
+  "AllowedHosts": "*"
+}

services/bff/Bff.Tests/Bff.Tests.csproj

@@ -0,0 +1,26 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <IsPackable>false</IsPackable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="coverlet.collector" Version="6.0.4" />
+    <PackageReference Include="Microsoft.AspNetCore.Mvc.Testing" Version="10.0.8" />
+    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.14.1" />
+    <PackageReference Include="xunit" Version="2.9.3" />
+    <PackageReference Include="xunit.runner.visualstudio" Version="3.1.4" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <Using Include="Xunit" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\Bff.Api\Bff.Api.csproj" />
+  </ItemGroup>
+
+</Project>

services/bff/Bff.Tests/HealthEndpointTests.cs

@@ -0,0 +1,20 @@
+using System.Net;
+using Microsoft.AspNetCore.Mvc.Testing;
+
+namespace Bff.Tests;
+
+public class HealthEndpointTests(WebApplicationFactory<Program> factory)
+    : IClassFixture<WebApplicationFactory<Program>>
+{
+    [Fact]
+    public async Task Health_endpoint_returns_200_and_reports_healthy()
+    {
+        var client = factory.CreateClient();
+
+        var response = await client.GetAsync("/health");
+
+        Assert.Equal(HttpStatusCode.OK, response.StatusCode);
+        var body = await response.Content.ReadAsStringAsync();
+        Assert.Contains("Healthy", body);
+    }
+}

services/bff/Bff.slnx

@@ -0,0 +1,4 @@
+<Solution>
+  <Project Path="Bff.Api/Bff.Api.csproj" />
+  <Project Path="Bff.Tests/Bff.Tests.csproj" />
+</Solution>

services/bff/Dockerfile

@@ -0,0 +1,30 @@
+# Multi-stage build for the placeholder BFF (.NET 10).
+# Build context is services/bff (see infra/docker-compose.yml).
+FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
+WORKDIR /src
+
+# Restore first (cached unless the csproj changes).
+COPY Bff.Api/Bff.Api.csproj Bff.Api/
+RUN dotnet restore Bff.Api/Bff.Api.csproj
+
+# Then build + publish.
+COPY Bff.Api/ Bff.Api/
+RUN dotnet publish Bff.Api/Bff.Api.csproj -c Release -o /app/publish /p:UseAppHost=false
+
+FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS runtime
+WORKDIR /app
+
+# curl is used by the container HEALTHCHECK / compose healthcheck.
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends curl \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY --from=build /app/publish .
+
+ENV ASPNETCORE_URLS=http://+:8080
+EXPOSE 8080
+
+HEALTHCHECK --interval=5s --timeout=3s --start-period=10s --retries=5 \
+    CMD curl -fsS http://localhost:8080/health || exit 1
+
+ENTRYPOINT ["dotnet", "Bff.Api.dll"]