From efbc6c43e379dcf6bfa41a51a5a8199841ac11a2 Mon Sep 17 00:00:00 2001 From: Edwin van den Houdt Date: Wed, 3 Jun 2026 13:57:18 +0200 Subject: [PATCH] ci: add Gitea Actions pipeline + runner runbook (refs #30) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add .gitea/workflows/ci.yaml with lint, build, unit, and compose-smoke jobs on runs-on: respellion-linux; uses: pinned to absolute tagged URLs (§8.7/§15). Document the runner in docs/runbooks/ci.md: the respellion- linux label, co-locating act_runner on the Gitea server in host mode, prerequisites, and a security note. The lint/build/unit/compose commands are verified locally. End-to-end "pipeline green" is deferred until a runner is registered, so this refs (does not close) #30; the issue stays open until CI runs green. Co-Authored-By: Claude Opus 4.8 --- .gitea/workflows/ci.yaml | 54 ++++++++++++++++++++++++++++ docs/runbooks/ci.md | 76 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 130 insertions(+) create mode 100644 .gitea/workflows/ci.yaml create mode 100644 docs/runbooks/ci.md diff --git a/.gitea/workflows/ci.yaml b/.gitea/workflows/ci.yaml new file mode 100644 index 0000000..ab49408 --- /dev/null +++ b/.gitea/workflows/ci.yaml @@ -0,0 +1,54 @@ +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). + +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' + - name: dotnet format (verify, no changes) + run: dotnet format services/bff/Bff.slnx --verify-no-changes + + 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: dotnet build services/bff/Bff.slnx -c Release + + 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: dotnet test services/bff/Bff.slnx -c Release + + 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 diff --git a/docs/runbooks/ci.md b/docs/runbooks/ci.md new file mode 100644 index 0000000..ac8bf97 --- /dev/null +++ b/docs/runbooks/ci.md @@ -0,0 +1,76 @@ +# 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 \ + --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.