Files
2026-10-26 14:40:12 +01:00

4.4 KiB

PipelineManager: Anweisungen für Coding-Agenten

Zuerst lesen

  1. README.md: Architektur, Befehle und Konfigurationsvertrag.
  2. docs/BETRIEB.md: tatsächlicher Betriebsstand, Nachweise und Fehlerbehandlung.
  3. docs/PROJEKTE-ANBINDEN.md: neue Anwendungen und Referenz-Workflow.
  4. Vor Änderungen git status prüfen; fremde Änderungen erhalten.

Vereinbarte Architektur

PipelineManager ist eine wiederverwendbare Deployment-Werkzeugkette, kein dauerhaft laufender API-Dienst. Gitea verwaltet Aufträge und Logs. Der Runner startet kurzlebige Container aus einem bereits gebauten, versionierten Image. Container erzeugen selbst keine weiteren Container. Kein Docker-Socket im Job-Container, keine veröffentlichten Ports, kein MCP erforderlich. Diese Architektur nicht ohne ausdrückliche Abstimmung durch einen Server/API-Dienst ersetzen.

  • Dieses Repository: Werkzeuge, Konfigurationsvertrag, generische Paketprüfung, Sicherung, SSH-Übertragung, Aktivierung und Rückfall.
  • Anwendungsrepository: pipeline.toml, eigene Tests, Build-/Aktivierungsbefehle und Gitea-Workflow.
  • Strato: PHP-/Datei-Laufzeit, persistente Daten und Server-Konfiguration. Keine Node-Installation zur Laufzeit.
  • Keine Laravel-, MediaWiki-, Mandanten- oder projektspezifische Fachlogik im Manager.

Änderungen am Manager

  • Python-Standardbibliothek, Python >= 3.11; bestehende Konventionen verwenden.
  • Vor Codeänderungen vorhandene Tests lesen. python -m unittest discover -s tests -v ausführen; für Verhaltensänderungen gezielte Regressionstests ergänzen.
  • Remote-Shell zusätzlich mit bash -n manager/remote.sh prüfen; der echte Image-Build läuft über Gitea auf dem Pi.
  • Release-Version in VERSION und manager/cli.py zusammen ändern. Bestehende v*-Tags oder freigegebene Images niemals auf einen anderen Stand umbiegen.
  • Kandidaten-Build grün abwarten, danach neuen Versionstag veröffentlichen und dessen Freigabelauf prüfen. Anwendungs-Konfiguration und Workflow müssen dieselbe Manager-Version verwenden.
  • Dokumentationsänderungen benötigen keine neue Werkzeugversion. Ein neuer Kandidaten-Build gibt noch keine neue stabile Version frei.
  • Anwendungen und produktive Dienste auf dem Pi nicht verändern, um Manager-Tests zum Bestehen zu bringen.

Änderungen in einer Anwendung

  • Quellstände einschließlich externer Quellen und Erweiterungen fest pinnen; keine beweglichen latest-/Branch-Downloads als Releasebasis.
  • Tests im Container vor dem Upload ausführen. Kein voller Build auf dem Entwicklungsrechner als Voraussetzung für den CI-Weg.
  • Build-Container bekommt keine Strato-Secrets. Deployment-Container bekommt sie nur im Deployment-Schritt.
  • Pflichtdateien und Ausschlüsse ausdrücklich konfigurieren. Symlinks im Quell-Export oder Paket sind in Vertrag 1 nicht unterstützt. Exclude-Pfade sind wörtliche relative Pfade, keine Globs.
  • Schreibbare Dateien, Uploads und Konfiguration über remote.shared erhalten. shared vor Erstinstallation separat einrichten; niemals Daten anderer Ziele übernehmen.
  • Keine Änderungen nach prepare am erzeugten Paket; Paket und SHA256 gehören zusammen.
  • develop -> Test; Merge-Commit von develop nach main -> Produktion. Gesperrte Ziele nicht eigenmächtig aktivieren.

Geheimnisse und Grenzen

  • Private Schlüssel, Passwörter und Tokens ausschließlich in Gitea Secrets oder geschützter Server-Konfiguration. Niemals in Git, Beispiele, Image, Logs oder Chat schreiben.
  • Hostschlüssel vorab verifizieren; StrictHostKeyChecking nicht abschalten.
  • Backups enthalten .env und Datenbankdaten. Nur geschützte persistente Verzeichnisse verwenden; niemals als öffentliche CI-Artefakte veröffentlichen.
  • Pi-Dateien unter /home/lars/docker/pipeline-manager/; keine offenen Ports erforderlich. Andere Docker-Projekte nicht anfassen.
  • Ein freigegebenes Image liegt aktuell nur lokal auf Raspi5-Paperless. Nicht auf einen anderen Runner wechseln, ohne dort ein passendes Image bereitzustellen.
  • Keine parallelen Aufträge gegen dasselbe Ziel erzwingen, keine fremden Sperren entfernen. Rückfall betrifft Code; Datenbankänderungen werden nicht automatisch rückgängig gemacht.

Abschluss und Übergabe

Nach wesentlichen Änderungen Betriebsstand und Nachweise aktualisieren: Commit, Image-Version, Gitea-Lauf, Ziel, Tests, HTTP-Prüfung, offene Punkte. Ein grüner Unit-Testlauf allein ist kein erfolgreicher Strato-Deploy. Tatsächlich ausgeführte Prüfungen von geplanten Prüfungen unterscheiden.