tessera-ctl/docs/ci-cd-setup.md

Tessera CI/CD Setup

Runbook fuer die Einrichtung der Gitea-basierten CI/CD-Pipeline.

Voraussetzungen

• Docker und Docker Compose installiert
• Gitea-Instanz mit aktivierten Actions
• Zugriff auf die Gitea-Administrationsoberflaeche

1. Gitea-Repository einrichten

1. In Gitea ein neues Repository erstellen (z.B. tessera-ctl)
2. Das Repository als Git-Remote hinzufuegen:

git remote add origin https://<gitea-url>/<user>/tessera-ctl.git

3. In den Repository-Einstellungen unter Settings > Actions sicherstellen, dass Actions aktiviert ist.

2. act_runner registrieren

Der act_runner fuehrt Gitea Actions Workflow-Jobs in Docker-Containern aus.

Runner-Token generieren

1. In Gitea navigieren zu: Repository > Settings > Actions > Runners (oder Admin-Panel > Actions > Runners fuer globale Runner)
2. Create registration token klicken
3. Token kopieren

Runner starten

Die Umgebungsvariablen setzen (z.B. in .env im Projektverzeichnis oder direkt in der Shell):

export GITEA_INSTANCE_URL=https://git.vicolab.de
export GITEA_RUNNER_REGISTRATION_TOKEN=<token-aus-schritt-oben>

Runner starten:

docker compose -f docker-compose.ci.yml up -d

Runner-Status pruefen:

docker compose -f docker-compose.ci.yml logs act_runner

Der Runner registriert sich automatisch bei Gitea und ist bereit, Jobs auszufuehren.

Bestehender Runner

Wenn bereits ein act_runner als separater Docker-Container laeuft (z.B. gitea-runner), kann docker-compose.ci.yml als Dokumentation und Vorlage fuer eine Neueinrichtung verwendet werden. Der bestehende Runner muss nicht ersetzt werden.

Bestehenden Runner pruefen:

docker ps --filter name=gitea-runner

3. Erforderliche Konfiguration

Umgebungsvariablen

Variable	Beschreibung	Wo setzen
GITEA_INSTANCE_URL	URL der Gitea-Instanz	.env oder Systemumgebung
GITEA_RUNNER_REGISTRATION_TOKEN	Runner-Registrierungstoken	.env oder Systemumgebung

Gitea Secrets (fuer die CI-Pipeline)

In Gitea unter Repository > Settings > Actions > Secrets koennen Secrets fuer die Pipeline konfiguriert werden. Aktuell werden keine Secrets in der Pipeline benoetigt, da Images lokal gebaut und deployed werden (kein Registry-Push).

Falls kuenftig Deploy-Pfade oder Credentials benoetigt werden:

1. In Gitea Settings > Actions > Secrets den Secret anlegen
2. In .gitea/workflows/ci.yml ueber ${{ secrets.SECRET_NAME }} referenzieren

Wichtig: Secrets niemals in Logs ausgeben oder in Workflow-Dateien hardcoden.

4. Pipeline-Ueberblick

Die CI/CD-Pipeline (.gitea/workflows/ci.yml) wird bei jedem Push auf main ausgefuehrt und besteht aus drei aufeinander aufbauenden Jobs:

1. quality -- Lint (Biome) und TypeScript Type-Check
2. test -- Vitest Unit- und Integrationstests
3. build-deploy -- Docker Images bauen und Services neu starten

Ablauf: quality -> test -> build-deploy (jeder Job nur bei Erfolg des vorherigen).

Kein Registry-Push

Images werden lokal auf dem Server gebaut und nicht in eine Registry gepusht (D-13). Da der Runner und die Applikation auf demselben Server laufen, baut die Pipeline die Images direkt mit docker compose build und startet die Services mit docker compose up -d neu.

Vorteile:

• Keine Registry-Infrastruktur noetig
• Schnellerer Deploy (kein Push/Pull ueber Netzwerk)
• Einfachere Konfiguration

5. Sicherheitshinweise

Docker Socket

Der act_runner mountet den Host-Docker-Socket (/var/run/docker.sock), um Jobs in Docker-Containern ausfuehren zu koennen. Das bedeutet:

• Der Runner hat Zugriff auf den Docker-Daemon des Hosts
• Er kann Container starten, stoppen und inspizieren

Risikobewertung: Akzeptabel fuer interne CI, da:

• Nur Claude pusht manuell bei Meilensteinen (D-11)
• Kein externer Code wird ausgefuehrt
• Ephemeral Mode ist aktiviert (siehe unten)

Ephemeral Runner

GITEA_RUNNER_EPHEMERAL=1 sorgt dafuer, dass der Runner seine Credentials nach jedem Job widerruft und sich neu registriert. Das verhindert:

• Persistente Zugriffstokens im Runner-Container
• Kompromittierung ueber alte Job-Artefakte
• Seitliche Bewegung zwischen Jobs

Workflow-Dateien

Workflow-Dateien in .gitea/workflows/ werden direkt aus dem Repository geladen. Da nur vertrauenswuerdiger Code gepusht wird (D-11, Claude als einziger Committer), ist das Risiko einer manipulierten Pipeline minimal.

6. Fehlerbehebung

Runner registriert sich nicht

1. Pruefen ob GITEA_INSTANCE_URL korrekt und erreichbar ist
2. Token ggf. neu generieren (Token sind einmalig verwendbar bei Ephemeral Mode)
3. Runner-Logs pruefen: docker compose -f docker-compose.ci.yml logs act_runner

Pipeline startet nicht

1. In Gitea pruefen ob Actions fuer das Repository aktiviert ist
2. Pruefen ob der Runner als "online" angezeigt wird (Gitea > Actions > Runners)
3. Sicherstellen dass die Workflow-Datei unter .gitea/workflows/ liegt
4. YAML-Syntax validieren

Docker-Build schlaegt fehl

1. Sicherstellen dass docker-compose.yml im Arbeitsverzeichnis des Runners erreichbar ist
2. Docker Daemon Status pruefen: docker info
3. Disk Space pruefen: df -h