From e5aea84539f057a2230d0501d65bd9e9881a9f0e Mon Sep 17 00:00:00 2001
From: nexxo <nexxo@clupilot.local>
Date: Sun, 26 Jul 2026 01:18:42 +0200
Subject: [PATCH] docs(ci): wire the runner up to the point where only the
 token is missing

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .env.example       |  9 +++++++++
 docs/deployment.md | 29 +++++++++++++++++++++++++++++
 2 files changed, 38 insertions(+)

diff --git a/.env.example b/.env.example
index 529feba..64ab490 100644
--- a/.env.example
+++ b/.env.example
@@ -189,3 +189,12 @@ VITE_AUTOSTART=false
 VITE_PORT=5173
 REVERB_HOST_PORT=8080
 DB_HOST_PORT=3306
+
+# ── CI (Gitea Actions) ──────────────────────────────────────────────────────
+# Registrierungs-Token aus Gitea: Repo → Settings → Actions → Runners →
+# "Create new runner". Danach:  docker compose --profile ci up -d runner
+GITEA_INSTANCE_URL=https://git.bave.dev
+GITEA_RUNNER_TOKEN=
+GITEA_RUNNER_NAME=clupilot-local
+# Passend zur Server-Version halten (1.20 verträgt keinen aktuellen Runner).
+GITEA_RUNNER_VERSION=0.2.6
diff --git a/docs/deployment.md b/docs/deployment.md
index 008ea6a..02d7c26 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -77,3 +77,32 @@ Settings → Website visibility. Outsiders then get a placeholder (503,
 `noindex`), while anyone on the management VPN and any signed-in operator keeps
 seeing the real thing. The console stays reachable either way, so the switch can
 always be flipped back.
+
+## CI (Gitea Actions)
+
+`.gitea/workflows/tests.yml` runs the Pest suite and an asset build on every
+push, and tags a green `main` as `tested-…`. That tag is what the console will
+offer as an available update — a red run produces no tag and therefore no
+update.
+
+Actions has to be switched on twice: globally in Gitea's `app.ini`
+(`[actions] ENABLED = true`, then restart) and per repository under
+Settings → Advanced. Verify with:
+
+```bash
+curl -s -H "Authorization: token <token>" \
+  https://git.bave.dev/api/v1/repos/boban/CluPilotCloud | grep -o '"has_actions":[a-z]*'
+```
+
+The runner is an opt-in compose service. Fetch a registration token from
+Settings → Actions → Runners → "Create new runner" (Gitea 1.20 has no API for
+it), put it in `.env` as `GITEA_RUNNER_TOKEN`, then:
+
+```bash
+docker compose --profile ci up -d runner
+```
+
+Keep `GITEA_RUNNER_VERSION` in step with the server: the registration protocol
+moves with Gitea, and a runner newer than the server refuses to register.
+The `uses:` steps are fetched from github.com, so the runner needs outbound
+internet — the code itself never leaves your Gitea.