4.4 KiB
PipelineManager: Anweisungen für Coding-Agenten
Zuerst lesen
README.md: Architektur, Befehle und Konfigurationsvertrag.docs/BETRIEB.md: tatsächlicher Betriebsstand, Nachweise und Fehlerbehandlung.docs/PROJEKTE-ANBINDEN.md: neue Anwendungen und Referenz-Workflow.- Vor Änderungen
git statusprü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 -vausführen; für Verhaltensänderungen gezielte Regressionstests ergänzen. - Remote-Shell zusätzlich mit
bash -n manager/remote.shprüfen; der echte Image-Build läuft über Gitea auf dem Pi. - Release-Version in
VERSIONundmanager/cli.pyzusammen ändern. Bestehendev*-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.sharederhalten.sharedvor Erstinstallation separat einrichten; niemals Daten anderer Ziele übernehmen. - Keine Änderungen nach
prepaream erzeugten Paket; Paket und SHA256 gehören zusammen. develop-> Test; Merge-Commit vondevelopnachmain-> 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
.envund 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.