Files
PipelineManager/AGENTS.md
T
2026-10-26 14:40:12 +01:00

50 lines
4.4 KiB
Markdown

# 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.