docs(runner-setup): Sichtbarkeit idf-ci, Security-Einschätzung

docs/runner-setup.md

@@ -10,6 +10,37 @@ Der Runner ist ein einzelnes ausführbares Binary (`act_runner`), das sich beim
 
 Der Runner **baut** die Plugin-ZIPs und legt sie als Gitea-Release-Assets ab. Er **verteilt** nichts an Kunden — das ist Aufgabe des Master-Key-Plugins.
 
+## Voraussetzungen in Gitea
+
+Damit der Runner Reusable-Workflows aus `idf-ci` lesen kann, muss das Repo für ihn erreichbar sein. Der beim Job generierte Token ist nur für das aufrufende Plugin-Repo gültig und kann kein anderes privates Repo klonen.
+
+**Daher: `ideenfabrik/idf-ci` muss auf Sichtbarkeit „Public" (oder „Limited", falls in der Gitea-Version verfügbar) stehen.**
+
+- **Public** — lesbar für alle, die die Gitea-Instanz erreichen.
+- **Limited** — lesbar für alle eingeloggten Gitea-User. In neueren Gitea-Versionen verfügbar. Für unseren Fall äquivalent zu Public, weil der Runner eh mit Token angemeldet ist.
+- **Private** — funktioniert nicht, weil der Job-Token keinen Repo-übergreifenden Lesezugriff hat.
+
+### Ist das ein Sicherheitsproblem?
+
+Das Risiko ist niedrig, weil das Repo ausschließlich CI-Baustoff enthält:
+
+- Keine Access-Tokens, API-Keys oder Passwörter (Secrets werden zur Laufzeit injiziert, nie committet)
+- Keine Plugin-Quellcodes, keine Business-Logik, keine Kundendaten
+- Kein Zugriff auf Produktions-Systeme
+
+Öffentlich lesbar sind nur: der Release-Workflow (Bau-Logik), die Doku und das Caller-Template. Standard-CI-Praxis, wie bei vielen Open-Source-Projekten.
+
+Falls der Gitea-Server aus dem Internet erreichbar ist, bedeutet „Public" tatsächlich weltweit lesbar. Ist der Gitea-Server nur intern/VPN-gebunden erreichbar, ist „Public" effektiv identisch mit „intern lesbar". Im Zweifel: Sichtbarkeit auf „Limited" setzen, dann muss man wenigstens angemeldet sein, um zu lesen.
+
+### Umstellung
+
+1. Repo öffnen: https://git.ihre-ideenfabrik.de/ideenfabrik/idf-ci
+2. Settings → ganz runterscrollen → „Danger Zone"
+3. **Change Visibility** → Public (oder Limited, falls verfügbar)
+4. Bestätigen
+
+Einmalige Aktion pro Instanz.
+
 ## Voraussetzungen auf dem Server
 
 - Linux (Debian/Ubuntu; der IDF-Plesk-Host reicht)
@@ -154,6 +185,9 @@ Damit ist das komplette Build-System portabel: die Bauanleitung lebt in diesem R
 **Warnung `Labels from command will be ignored` beim Registrieren.**
 Du hast `--labels …` als CLI-Flag gesetzt, aber `act_runner` nimmt Labels nur aus der Config. Schritt 2 durchgehen, Labels in `config.yaml` eintragen. Dann `sudo rm /opt/act_runner/.runner`, neuen Token holen, Registrierung ohne `--labels`-Flag erneut ausführen.
 
+**Run bricht ab mit `Unable to clone … authentication required`.**
+`idf-ci` steht auf Private. Abschnitt „Voraussetzungen in Gitea" durchgehen und Sichtbarkeit auf Public (oder Limited) setzen. Danach den Run über den Re-run-Button in der Gitea-Actions-UI neu starten — kein Re-Tagging nötig.
+
 **Runs hängen auf `queued`, Runner steht aber auf Online.**
 Label-Mismatch. Der Workflow schreibt `runs-on: self-hosted`, der Runner muss dasselbe Label anbieten. In der Gitea-UI die Labels des Runners prüfen — stehen dort nicht `self-hosted, linux, x64`, liegt es an Schritt 2.