diff --git a/.gitea/workflows/ci.yaml b/.gitea/workflows/ci.yaml index ab49408..2f0be4c 100644 --- a/.gitea/workflows/ci.yaml +++ b/.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: dotnet format services/bff/Bff.slnx --verify-no-changes + - run: make lint 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: 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 + - run: make smoke diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..f28b612 --- /dev/null +++ b/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/^## //' diff --git a/docs/runbooks/ci.md b/docs/runbooks/ci.md index ac8bf97..4e84e5d 100644 --- a/docs/runbooks/ci.md +++ b/docs/runbooks/ci.md @@ -1,26 +1,54 @@ # 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. +> **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`. 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 | -| `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 | +| `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`**