KI-unterstützte Entwicklung

Vom Auftrag zum nachweisbaren Ergebnis

KI-unterstützte Entwicklung verbindet menschliche Urteilskraft mit Agenten, die Projektkontext lesen, Code ändern, Werkzeuge bedienen und Ergebnisse prüfen können. Der oft verwendete Begriff «Vibecoding» beschreibt nur einen Teil dieses Spektrums. Wir zeigen einen Arbeitsablauf, in dem Du auch ohne DevOps-Erfahrung verstehst, was gerade geschieht, welche Entscheidung ansteht und welcher Nachweis noch fehlt.

Der Kurs richtet sich an Entwicklerinnen und Entwickler, technische Projektverantwortliche und erfahrene Quereinsteigende. Du kannst die Fallsequenzen zunächst lesend und im simulierten Labor bearbeiten. Für echte Änderungen benötigst Du einen freigegebenen Projektzugang. Plane für den ganzen Lernpfad mehrere Etappen ein; die beiden Migrationen sind voneinander unabhängig.

Ein durchgehendes Beispiel begleitet uns: eine interne Anwendung mit Aufgaben, Bearbeitungsständen und Benachrichtigungen. Das ist ein synthetisches Lernprojekt. Die unten genannten Platzhalter sind keine Zugangsdaten. Ersetze sie in Deinem Auftrag durch verifizierte Angaben, bevor ein Agent handelt.

• Kontext und Werkzeuge
• GitLab, Aufgaben und Fortschritt
• Lokaler und Cloud-Zugang
• Fall A: bestehende Proxmox-Anwendung
• Fall B: GitHub nach GitLab CE
• Ein neues Projekt beginnen
• CI, Container und Bereitstellung
• DNS, TLS und Rückweg
• Vier Handbücher
• Promptwerkstatt

1. Kontext, Regeln und Werkzeuge auseinanderhalten

Ein guter Auftrag nennt Ziel, Ausgangslage, erlaubte Änderungen und beobachtbare Abnahmekriterien. «Erstelle eine Anmeldung» lässt zentrale Fragen offen. «Ein bestätigtes Mitglied kann sich mit Passkey anmelden; Gäste erhalten keinen direkten Dateizugriff auf Mitgliederinhalte» ist überprüfbar. Projektunterlagen und vorhandener Code helfen dem Agenten, diese Kriterien in die tatsächliche Anwendung einzuordnen.

AGENTS.md: Wie wird in diesem Projekt gearbeitet?

Hier stehen Git-Wurzel, Architektur-Einstieg, Prüfkommandos, Zuständigkeiten und Grenzen für sensible Daten. Codex kombiniert globale und projektbezogene Anweisungen nach seiner dokumentierten Suchreihenfolge. Halte die Datei knapp und verweise auf gepflegte Handbücher. Projektregeln sind Anweisungen; die tatsächlichen Zugriffsrechte begrenzen weiterhin Betriebssystem, Plattform und Werkzeuge. OpenAI: AGENTS.md.

Skills: Welches wiederholbare Verfahren passt zur Aufgabe?

Ein Skill bündelt ein Verfahren in SKILL.md und gegebenenfalls Vorlagen, Referenzen oder Skripten. Ein passender Skill kann beispielsweise die Prüfung einer Oberfläche oder die Pflege von Architekturdiagrammen strukturieren. Prüfe Herkunft, Geltungsbereich und benötigte Werkzeuge vor der Verwendung. Ein Skill ist keine zusätzliche Berechtigung. OpenAI: Skills.

In einer passenden Codex-Umgebung kannst Du einen verfügbaren Skill ausdrücklich im Auftrag nennen, zum Beispiel über $skill-name. Der Name muss zu einem tatsächlich vorhandenen Skill passen. Der Agent liest dessen Anleitung und prüft, ob sie für die Aufgabe gilt; die blosse Erwähnung macht einen fehlenden Skill nicht verfügbar.

MCP, Tools und Integrationen: Was kann der Agent tatsächlich tun?

Ein Tool ist eine konkrete aufrufbare Fähigkeit, etwa eine Datei lesen, einen Browser bedienen oder einen Jobstatus abfragen. MCP ist ein Protokoll, über das unterstützte Clients solche Werkzeuge und Datenquellen anbinden können. Eine Integration verbindet einen Dienst mit einem Arbeitsablauf, beispielsweise GitLab mit einem CLI-Zugang oder einer Agentenumgebung. Nicht jede Integration verwendet MCP. Eine sichtbare Werkzeugbeschreibung beweist weder erfolgreiche Anmeldung noch Zugriff auf Dein Projekt. OpenAI: MCP.

Wir wählen deshalb zuerst das Verfahren, dann die nötigen Werkzeuge und schliesslich den eng begrenzten Zugang. Eine Dokumentationsrecherche benötigt beispielsweise lesenden Zugriff; ein Merge Request benötigt andere Rechte als eine Produktionsbereitstellung.

2. Self-hosted GitLab CE als gemeinsamer Arbeitsstand

Git speichert den versionierten Quellcode. Unser selbst betriebenes GitLab CE ergänzt Aufgaben, Merge Requests, CI/CD und Registry. git push überträgt keine vollständige Projektverwaltung. Für den Unterschied zwischen Repository, Plattform und Prüfablauf findest Du die Grundlagen im Git-Lernpfad; das Git-Szenarienlabor lässt Dich typische Entscheidungen erproben.

glab gibt Agenten einen strukturierten Zugang zu GitLab über die Kommandozeile. Vor der Arbeit müssen die ausgewählte Instanz, das Repository und die verfügbaren Rechte stimmen. Neuere CLI-Versionen können andere Unterbefehle besitzen als eine ältere Installation. Wir prüfen daher glab --version und die Hilfe zum benötigten Befehl. glab api ermöglicht zusätzliche REST- und GraphQL-Aufrufe; eine Mutation bleibt dabei eine echte Änderung. GitLab CLI und API-Aufrufe mit glab.

Ein Workitem ist eine kleine Vereinbarung

Für jede Aufgabe halten wir Problem, gewünschtes Verhalten, Abnahme, verantwortliche Person oder Agent, Abhängigkeiten und Ausschlüsse fest. Je nach installierter GitLab-/CLI-Version verwenden wir den passenden Workitem-Typ oder ein Issue. Erweiterte Planungsfunktionen dürfen in GitLab CE nicht einfach vorausgesetzt werden. GitLab: Workitems.

Fortschritt wird an Nachweisen sichtbar: «offen», «in Arbeit», «blockiert», «im Review» und «abgenommen» haben klare Bedeutungen. Ein Agent aktualisiert das zugehörige Workitem mit erledigtem Schritt, Commit, Prüfresultat und nächster Abhängigkeit. Ein grüner Job bedeutet nicht automatisch «live». Ein blockierter Auftrag benennt die konkret fehlende Evidenz. Wir schliessen die Aufgabe erst, wenn ihre Abnahmekriterien tatsächlich erfüllt sind.

3. Lokale und Cloud-Agenten erreichen nicht dieselbe Umgebung

Ein lokaler Agent kann vorhandene SSH-Konfiguration, lokale Werkzeuge und zugelassene Netzwerkwege nutzen, soweit seine Umgebung das erlaubt. Eine Cloud-Ausführung besitzt diese Zugänge nicht automatisch. Insbesondere werden ~/.ssh/config, private Schlüssel, interner DNS und eine lokale VPN-Verbindung nicht durch den Namen einer Git-Remote in die Cloud übertragen.

Für jeden Ausführungsort prüfen wir getrennt: Namensauflösung, Route, TCP-Port, TLS-Vertrauenskette beziehungsweise SSH-Hostschlüssel, Anmeldung und Projektberechtigung. Danach testen wir eine harmlose Leseoperation. HTTPS für GitLab/API, SSH für Git und der HTTPS-Endpunkt der Registry können verschiedene Namen, Ports und Zugangsmittel verwenden. Ein erfolgreicher Git-Clone beweist deshalb noch keinen Registry-Pull.

Für Cloud-Agenten kommen beispielsweise ein freigegebener privater Netzwerkzugang, ein abgesicherter Vermittlungsdienst oder ein passender Ausführungsort innerhalb des eigenen Netzes infrage. Welche Lösung verfügbar ist, hängt von Plattform und Infrastruktur ab. Wir öffnen weder GitLab noch die Anwendung pauschal ins Internet, nur damit ein Agent sie erreicht. Zertifikatsprüfung oder Hostschlüsselprüfung abzuschalten wäre ebenfalls kein Zugangskonzept.

Aktuelle Codex-Cloud-Dokumentation unterscheidet direkte Umgebungswerte und HTTPS-Netzwerk-Secrets; letztere werden für erlaubte Ziele über einen Proxy eingesetzt. Daraus folgt kein allgemeiner SSH-Zugang. Private Netzwerkunterstützung muss in der konkreten Umgebung eingerichtet und in einer neuen Aufgabe geprüft werden. OpenAI: Cloud-Umgebungen.

Eine Zugangsmatrix nennt für GitLab/API, Git-SSH, Registry, Testoberfläche und Zielhost jeweils FQDN, Port, Netzwerkweg, Identität und erlaubte Aktionen. Zugangsdaten bleiben in geschützten Secret-Dateien oder einer geeigneten Secret-Verwaltung. Der Agent berichtet den Erfolg der Prüfung, nicht die Inhalte der Zugangsmittel.

Zugang in der aktiven Agentenphase nachweisen

Ein erfolgreicher Setup-Schritt reicht nicht. In der späteren Agentenphase prüfen wir erneut eine authentifizierte API-Leseanfrage mit glab api projects/<URL_ENCODED_PROJECT_PATH>, die Git-Referenzen mit git ls-remote <READ_REMOTE_URL> und einen authentifizierten Registry-Metadatenabruf, bei entsprechender CLI-Unterstützung beispielsweise docker manifest inspect <IMAGE_AT_DIGEST>. Die Platzhalter werden vor Verwendung ersetzt. Nur nötige Ergebnisse ausgeben; URL und Ausgaben dürfen keine Zugangsdaten enthalten. Git: ls-remote und Docker: manifest inspect.

Ein API-Header über ein HTTPS-Netzwerk-Secret versorgt nicht automatisch einen Git-Credential-Helper, eine Base64-kodierte HTTP-Authentisierung, SSH oder den Tokenaustausch der Registry. Wir verwenden eine unterstützte verwaltete GitLab-Anbindung, falls verfügbar, oder einen geeigneten Agentenhost mit minimaler, geschützter Zugangsinjektion. Echte Tokens werden nicht in gecachte Konfiguration geschrieben.

Die Registry kann für Bearer-Authentisierung auf einen anderen Authentisierungs-Endpunkt verweisen; Blob-Downloads können weitere Hosts benötigen. Netzwerkfreigaben müssen die tatsächlich verwendeten Registry-, Auth-Realm- und gegebenenfalls Blob-Ziele abdecken. Eine nicht authentifizierte Antwort 401 am Registry-Eingang zeigt allein noch keinen erfolgreichen Pull. GitLab: Registry-Authentisierung.

4. Fall A: Eine interne Proxmox-Anwendung ohne Git und TLS übernehmen

Ausgangslage: Eine kleine Anwendung läuft in einer VM oder einem Container auf Proxmox, erreichbar über internes HTTP. Quellcode liegt teilweise in einem Codex-Arbeitsverzeichnis unter ~/.codex. Es gibt keinen belastbaren Git-Verlauf. Ziel ist ein privates Projekt auf dem eigenen GitLab CE, eine reproduzierbare Bereitstellung und ein nachvollziehbarer Betriebsweg. «Ohne TLS» beschreibt den Altzustand, keine Empfehlung für die Zukunft.

Schritt 1: Den laufenden Zustand verstehen

Wir sammeln Startmechanismus, Prozess oder Container, Quellverzeichnis, Abhängigkeiten, Datenbank, Dateianhänge, Benutzer, Netzwerkports und aktuelle URL. Wir prüfen, ob VM und Anwendung tatsächlich derselben Quellkopie entsprechen. Ergebnis ist eine Bestandskarte mit offenen Fragen. Es wird noch nichts verschoben oder neu gestartet.

Schritt 2: Quelle von Agenten-Laufzeit trennen

~/.codex ist kein pauschal freigegebenes Quellarchiv. Dort können zusätzlich Verlauf, Konfiguration, Logs oder Zugangsinformationen liegen. Wir identifizieren den konkreten Anwendungsordner und prüfen Symlinks sowie eingebettete Git-Repositories. Nur freigegebene Anwendungsdateien gelangen in einen eigenen Projektordner. Originale bleiben als Wiederherstellungsgrundlage erhalten.

Schritt 3: Daten und Rückweg sichern

Eine Quellkopie reicht nicht für die Wiederherstellung der laufenden Anwendung. Wir sichern die Datenbank mit einem dafür geeigneten Verfahren und erfassen persistente Dateien sowie nötige Konfiguration. Ein Proxmox-Snapshot kann ergänzen, ersetzt aber keine geprüfte anwendungskonsistente Sicherung. Wir prüfen einen Restore in einer getrennten Testumgebung und vereinbaren ein Rückkehrkriterium.

Schritt 4: Einen sauberen Projektanfang erzeugen

Im neuen Projektordner dokumentieren wir Herkunft und Ausgangsstand. Wir erstellen .gitignore, eine Secret-freie Beispielkonfiguration und AGENTS.md. Erst nach Dateiprüfung initialisieren wir Git und nehmen gezielt Quellcode, Tests und Dokumentation auf. Datenbanken, reale .env-Dateien, Agentenverlauf und Sicherungen bleiben ausserhalb. Der erste Commit ist eine nachvollziehbare Baseline, keine Behauptung, dass die Altanwendung bereits alle Tests besteht.

Schritt 5: GitLab-Zugang und Projekt einrichten

Wir prüfen den Zugang zum eigenen GitLab CE und legen ein privates Projekt im vereinbarten Namespace an. Der Agent arbeitet nur mit den dafür freigegebenen Rechten. Anschliessend wird die richtige Remote hinzugefügt und der geprüfte Anfangsstand übertragen. Sichtbarkeit, Standardbranch und Hauptbranch-Schutz werden in GitLab kontrolliert. Eine private Projektablage macht enthaltene Geheimnisse nicht unbedenklich.

Schritt 6: Zuerst ohne Produktion testen

Wir beschreiben den lokalen Start mit festgelegten Abhängigkeiten und synthetischen Beispieldaten. Ein einfacher Verhaltenstest prüft die wichtigste Funktion; ein zweiter den wichtigsten Zugriffsfall. Fehlende Tests werden als Arbeitsaufgaben erfasst. Erst danach entstehen Containerdefinition und CI-Ablauf. Produktionsdaten werden nicht in den Build-Kontext kopiert.

Schritt 7: Testen, bauen und Artefakte zuordnen

Die CI prüft den konkreten Commit und baut das Image für die Architektur des Zielhosts. Das Image wird in die private Registry übertragen. Wir speichern Commit, Pipeline, Testnachweise und Image-Digest gemeinsam. Ein fehlerhafter Test wird behoben oder als nicht bestandene Abnahme ausgewiesen; die Prüfung einfach abzuschalten wäre kein Fortschritt.

Schritt 8: Den neuen Betriebsweg vorbereiten

Auf dem Zielhost planen wir Dienstbenutzer, Deployment-Verzeichnis, Datenbank, persistente Mounts, Secrets, Healthcheck und Reverse Proxy. Die bisherige Anwendung läuft weiter, während wir die neue Version getrennt prüfen. Für den künftigen FQDN klären wir DNS, Zertifikat und gegebenenfalls privaten Zugang. Ein Docker-Image enthält die Anwendung; es ist nicht die Sicherung ihrer beweglichen Daten.

Schritt 9: Kontrolliert umschalten

Vor dem Umschalten gibt es eine aktuelle Sicherung, ein kurzes Änderungsfenster und eine passende Datenübernahme. Datenbankmigrationen werden geplant, nicht beiläufig beim Start geraten. Danach prüfen wir die neue Anwendung direkt und über FQDN, Proxy und TLS sowie Anmeldung, zentrale Funktion und Persistenz. Bei verfehltem Rückkehrkriterium stellen wir den bekannten betriebsfähigen Stand wieder her.

Schritt 10: Erst nach Betriebsnachweis aufräumen

Wir dokumentieren die tatsächlich aktive Version und aktualisieren Architektur-, Benutzer-, Entwickler- und Betriebshandbuch. Der Altbetrieb wird erst nach vereinbarter Beobachtung und vollständiger Wiederherstellungsgrundlage abgeschaltet. Arbeitsverzeichnisse werden gezielt bereinigt; Agentenlaufzeit oder Proxmox-Volumes werden nicht pauschal gelöscht.

5. Fall B: GitHub nach eigenem GitLab CE übertragen

Ausgangslage: Das Projekt besitzt einen GitHub-Ursprung und einen Git-Verlauf. Es soll künftig auf dem eigenen GitLab CE gepflegt werden. Wir übertragen eine Arbeitsumgebung, nicht nur eine URL. Die Anwendung kann währenddessen an ihrem bisherigen Ort weiterlaufen.

Schritt 1: Quell- und Plattforminventar erstellen

Wir prüfen lokale Änderungen, Remotes, Standardbranch, relevante Branches, Tags, Submodule und LFS. Daneben erfassen wir Issues, Pull Requests und Reviews, Wiki, Releases samt Dateien, CI-Workflows, Variablen/Secrets, Pakete und Container-Registry, Webhooks, Deploy Keys, Integrationen und Branch-Regeln. Diese Bestände gehören nicht alle zum Git-Repository.

Schritt 2: Für jeden Bestand eine Übertragungsentscheidung treffen

Git-Verlauf kann mit Git übertragen werden. Ob Metadaten mit einem GitHub-Importer übernehmbar sind, hängt von verfügbarer GitLab-Version, aktiviertem Importweg und Zugriffsrechten ab. Die aktuelle Dokumentation beschreibt auch teilweise abgeschlossene Importe. Wir planen daher Stichproben und Vollständigkeitsabgleich, statt einer Erfolgsmeldung blind zu vertrauen. GitLab: GitHub-Import.

Secrets werden geschützt neu hinterlegt und bei Bedarf rotiert. GitHub Actions wird nicht automatisch zu einem fachlich gleichwertigen GitLab-CI-Ablauf. Registry-Images, Release-Dateien und Verknüpfungen erhalten einen expliziten Migrationsschritt. Nicht übernommene Historie bleibt mit nachvollziehbarem Archiv- oder Referenzpfad erhalten.

Schritt 3: Ziel und Sicherung vorbereiten

Wir sichern den bekannten Quellstand und erfassen die zu übertragenden Referenzen. Das private GitLab-Projekt, Namespace, Rechte und Speicherbedarf werden vorab geprüft. Der bisherige origin bleibt zunächst bestehen. Eine zusätzliche, eindeutig benannte GitLab-Remote erlaubt den Vergleich, ohne den alten Arbeitsweg zu verbergen.

Schritt 4: Übertragung in einem getrennten Migrationslauf prüfen

Wir wählen den geprüften Importweg und übertragen nur die vorgesehenen Branches und Tags. LFS-Inhalte und Submodule werden separat auf Vollständigkeit geprüft. Ein blinder push --mirror in ein bereits genutztes Ziel kann dortige Referenzen verändern oder löschen und ist kein sicherer Standardweg. Git: Bedeutung von Push und Mirror.

Schritt 5: Metadaten und Berechtigungen abgleichen

Wir vergleichen repräsentative Issues, Diskussionen, offene PR/MR, Wiki-Seiten, Releases und Links. Autoren- und Berechtigungszuordnung wird kontrolliert. Nicht unterstützte oder fehlgeschlagene Übernahmen erhalten einen dokumentierten Ersatzweg. Erst danach entscheiden wir, ob die Plattformmigration vollständig genug für den Arbeitswechsel ist.

Schritt 6: CI/CD bewusst neu verbinden

Wir übersetzen die fachlichen Prüfziele in .gitlab-ci.yml, verbinden geeignete Runner und hinterlegen nötige Secrets geschützt neu. Ein Testlauf baut ohne Produktionszugriff. Ein weiterer prüft gezielt die Registry und das spätere Deployment-Verfahren. Trigger und Webhooks werden so umgeschaltet, dass alte und neue Plattform nicht versehentlich dieselbe Produktionsänderung doppelt auslösen.

Schritt 7: Frischen Clone als Abnahme verwenden

Eine neue Arbeitskopie wird ausschliesslich aus GitLab erstellt. Daraus müssen Abhängigkeiten, LFS, Tests und Build funktionieren. Wir ordnen das Ergebnis dem Commit und dem später verwendeten Digest zu. Das prüft mehr als eine vorhandene Arbeitskopie, in der bislang unversionierte Dateien unbemerkt helfen könnten.

Schritt 8: Arbeitsort nach Freigabe umstellen

Nach erfolgreichem Abgleich erklären wir GitLab zum führenden Arbeitsort. Dann passen wir Remote-Bezeichnungen, Dokumentation, Projektverweise und Integrationen gezielt an. Der alte Ursprung wird zunächst lesend erhalten oder nach vereinbarter Aufbewahrung archiviert. Wir dokumentieren, wohin spätere Beiträge gehören und wie der Rückweg im Übergangszeitraum funktioniert.

6. Der kurze Weg für ein neues Projekt

1. Problem und Abnahme klären; kleine erste Funktion und ausgeschlossene Änderungen beschreiben.
2. Eigenen Projektordner und private GitLab-CE-Ablage festlegen. AGENTS.md, README, Beispielkonfiguration und die vier Handbuchgerüste mitführen.
3. Mit synthetischen Daten einen reproduzierbaren Start und einen sinnvollen Verhaltenstest schaffen.
4. Eine kleine Änderung auf einem Aufgabenbranch durchführen, Diff prüfen und einen MR mit Nachweisen erstellen.
5. CI und Registry erst mit getrennten Rechten verbinden. Für die erste Bereitstellung Daten, Secrets, FQDN, Proxy, TLS und Rückweg vorbereiten.
6. Nach der Live-Abnahme den Fortschritt im Workitem schliessen und die Handbücher mit dem tatsächlichen Stand nachführen.

7. CI und Bereitstellung sind unterschiedliche Vertrauensbereiche

Tests dürfen auch auf ungeprüften Beiträgen laufen. Ein Job mit Produktionsschlüssel oder einem privilegierten Container-Builder braucht dagegen eine passende Vertrauensgrenze. Wir trennen Prüfjobs, vertrauenswürdigen Build und Deployment nach Risiko und vergeben Produktionsrechte nur im vorgesehenen geschützten Ablauf. Ein Runner-Tag allein beweist diese Trennung nicht; Branch-Regeln, Runner-Konfiguration und die tatsächliche Jobzulassung müssen zusammenpassen. GitLab: Runner-Sicherheit.

Ein Builder mit Zugriff auf den Docker-Socket kann den zugehörigen Docker-Host steuern. Das ist eine weitreichende Vertrauensstellung, keine sichere Sandbox. Ein eigener Builder oder kurzlebiger, isolierter Runner kann diese Grenze anders gestalten; die tatsächliche Konfiguration entscheidet.

Ein Cache beschleunigt Arbeit und darf fehlen oder veraltet sein. Er ist weder Release-Nachweis noch Datensicherung. Testberichte und Build-Metadaten werden als zugeordnete Artefakte aufbewahrt; Image-Dateien liegen in der Registry. Der Digest identifiziert das bezogene Image eindeutig, beweist aber weder seine fachliche Korrektheit noch dauerhaft verfügbare Registry oder geschützte Herkunft. GitLab: Cache und Artefakte.

Auf dem Zielhost wird das geprüfte Image über <REGISTRY>/<PROJECT>@sha256:<DIGEST> bezogen. Ein begrenzter Deploy-Zugang ist etwas anderes als ein persönlicher Entwicklerzugang. Persistente Datenbank und Dateianhänge liegen in benannten Volumes oder bewusst gewählten Verzeichnismounts; Secrets werden geschützt separat bereitgestellt. Eine Container-Neuerstellung darf diese Daten nicht versehentlich ersetzen. GitLab: Deploy Tokens und Docker: Volumes.

Build-Daemon und Zielhost-Daemon besitzen getrennte Speicher. Bei Docker-in-Docker oder BuildKit liegt ein Cache gegebenenfalls nochmals an anderer Stelle. Auch ein vorhandenes Image auf demselben Host ist keine Verfügbarkeitsgarantie. Für parallele Bereitstellungen verwenden wir einen gemeinsamen Sperrmechanismus, beispielsweise eine passende GitLab-resource_group, und führen den Umgebungsstatus nach. Eine manuelle Aufgabe ist eine Ausführungsentscheidung; zusätzliche Deployment-Freigaben sind nicht in jeder GitLab-CE-Installation verfügbar. GitLab: Resource Groups.

Wo läuft der Runner, und was meldet der CD-Job?

Ein dedizierter Deploy-Runner kann auf dem Zielhost installiert sein. Alternativ verbindet sich ein vertrauenswürdiger Runner über einen begrenzten Fernzugang mit ihm. Unsere Empfehlung: Prüf- und Build-Code getrennt vom produktiven Dienst ausführen; der Deploy-Zugang erhält nur den vorgesehenen Projekt- und Umgebungsumfang. Der Runner auf dem Zielhost darf keine beliebigen Merge-Request-Jobs mit Produktionsrechten übernehmen.

Ein konkreter Ablauf ist: Tests → Image bauen und pushen → Digest erfassen → auf dem Zielhost ziehen → Sicherung und Migrationsverträglichkeit prüfen → Compose mit diesem Digest starten → Health und Benutzerweg prüfen. Der CD-Job wartet auf diese Ergebnisse und liefert verständliche Statusausgabe sowie einen bereinigten Prüfbericht. Mit environment wird das Deployment in GitLab zugeordnet; resource_group serialisiert konkurrierende Jobs. Bei Fehlern wird der geprüfte Rückweg ausgeführt und sein Ergebnis protokolliert. Der Job endet trotzdem fehlgeschlagen. GitLab: Environments.

Benannte Volumes, anonyme Volumes und Verzeichnismounts

Ein benanntes Volume hat einen bewusst gewählten Namen und einen dokumentierten Lebenszyklus. Ein anonymes Volume erhält einen zufälligen Namen; es kann einen Container überleben, wird von einem neuen Container aber nicht automatisch wiederverwendet. Deshalb verwenden wir für Datenbanken keine ungeklärten anonymen Volumes. Bei einer Übernahme erfassen wir zuerst die tatsächlich gemountete Volume-ID und ihre Daten, bevor wir die Definition ändern. Löschbefehle wie down -v oder ein globales Prune gehören nicht in den normalen Release-Ablauf.

Ein Bind Mount verbindet ein bestimmtes Hostverzeichnis mit dem Container. Wir dokumentieren Hostpfad, Containerpfad, UID/GID, Lese-/Schreibrechte, Kapazität und Sicherung. Konfiguration wird nach Möglichkeit nur lesend eingebunden. Falsche oder leere Mounts können vorhandene Daten verdecken; eine startende Anwendung kann dann wie eine Neuinstallation wirken. Ein neu erstellter Container muss auf dieselben geprüften Daten zugreifen. Das wird mit einem Testdatensatz und einer getrennten Restore-Probe nachgewiesen.

8. FQDN, Reverse Proxy, TLS und Wiederherstellung

Geschützte Variablen und Maskierung vermindern versehentliche Ausgabe, verhindern aber keine absichtliche Weitergabe durch einen zugelassenen Job. Auch dateibasierte Compose-Secrets sind nicht automatisch verschlüsselt. Quellrechte, Runnervertrauen und geschützte Ablage müssen deshalb zusammenpassen. Docker: Compose-Secrets.

Ein FQDN ist der vollständige DNS-Name der Anwendung, beispielsweise app.example.org. DNS muss ihn aus dem jeweils vorgesehenen Netz auf den richtigen Zugang zeigen lassen. Ein Reverse Proxy nimmt die Anfrage entgegen und leitet sie an den internen Dienst weiter. Das Zertifikat muss zum aufgerufenen Namen passen; eine funktionierende interne IP beweist deshalb keinen korrekten Browserzugang.

Bei Traefik beschreiben Compose-Labels unter anderem Host-Regel, EntryPoint, TLS-Resolver, Dienstport und nötiges Docker-Netz. Wir übernehmen die Namen des bestehenden Proxybetriebs nach Prüfung; wir erzeugen nicht nebenbei einen zweiten zentralen Ingress. Ein privater Dienst bleibt durch Netzwerk und Autorisierung privat, auch wenn er ein öffentlich vertrauenswürdiges Zertifikat erhält. Traefik: Docker-Routing.

Ein Wildcard-Zertifikat wie *.example.org deckt passende Namen einer Ebene ab, nicht automatisch den Basisnamen oder weitere Unterebenen. Für Wildcards verwendet ACME die DNS-01-Prüfung: Ein kontrollierter TXT-Eintrag weist die Verfügung über den Domainnamen nach. Die Anwendung muss dafür nicht öffentlich erreichbar sein; öffentlich prüfbarer DNS-Nachweis und ein geeigneter Domainname bleiben erforderlich. DNS-API-Zugänge werden eng begrenzt und geschützt beim Zertifikatsdienst gehalten. Let's Encrypt: Challenge-Typen und Traefik: ACME.

Ein erfolgreicher Rückweg stellt den Betrieb wieder her, macht aber die fehlgeschlagene neue Bereitstellung nicht nachträglich erfolgreich. Release-Ergebnis und aktueller Betriebszustand werden getrennt berichtet.

Ein Healthcheck beantwortet eine begrenzte Frage zur Bereitschaft des Dienstes. Wir prüfen zusätzlich den tatsächlichen Benutzerweg über Proxy und TLS, die Anmeldung und Datenbeständigkeit. Beim Rückweg unterscheiden wir Image, Konfiguration und Daten: Ein altes Image macht eine inkompatible Datenbankmigration nicht rückgängig. Vor der Änderung werden Migrationsverträglichkeit, Sicherung, Wiederherstellung, erlaubte Ausfallzeit und das Abbruchkriterium geklärt.

Secrets nach Zweck und Lebensphase trennen

• Erstkonfiguration: Ein initiales Administratorkonto wird über einen geschützten Bootstrap-Weg angelegt. Kein allgemein bekanntes Standardpasswort und keine Zugangswerte im Image. Einmalige Zugangsmittel anschliessend sperren oder rotieren; Erstlogin und Übergabe im Betriebshandbuch beschreiben.
• Tests: Wegwerfkonten und synthetische Daten verwenden. End-to-End-Tests bekommen einen eigenen minimal berechtigten Zugang aus geschützter Secret-Injektion. Screenshots, Videos, Traces und Testberichte vor Speicherung auf Zugangswerte prüfen.
• Deployment: Registry-Pull, Zielhost und GitLab-API benötigen unterschiedliche Rechte. Kurzlebige Job-Zugänge verwenden, wo unterstützt; andernfalls begrenzte Identitäten mit Rotation und dokumentiertem Ablaufdatum. Niemals einen persönlichen Vollzugriff pauschal an jeden Job weiterreichen.
• Anwendungsbetrieb: Interne Datenbank-/Dienstpasswörter und externe API-Keys getrennt nach Dienst und Umgebung halten. Nur der benötigte Container erhält den jeweiligen Wert. Dateien mit passenden Besitzerrechten oder ein geeigneter Secret-Dienst liefern ihn zur Laufzeit; .env ist kein Tresor und gehört nicht ins Repository.
• Verschlüsselung und Wiederherstellung: Passwörter werden mit einer geeigneten Passwort-Hashfunktion geprüft, nicht reversibel gespeichert. Daten, die entschlüsselt werden müssen, benötigen separat verwahrte Schlüssel. Schlüsselversion, Rotation, Wiederherstellung und Widerruf planen; ein verschlüsseltes Backup ohne wiederherstellbaren Schlüssel ist unbrauchbar. Schlüssel und Sicherung nicht gemeinsam ungeschützt ablegen.

Wir erfassen pro Secret Zweck, Verbraucher, Ablage, Verantwortliche, Gültigkeit, Rotation und Wiederherstellungsweg, niemals seinen Wert im Handbuch. Bei einer Offenlegung sperren oder rotieren wir den Zugang; blosses Löschen aus dem letzten Commit entfernt keine bereits kopierten Werte. OWASP: Secret-Lebenszyklus.

9. Vier Handbücher wachsen mit dem Projekt

Wir führen die Dokumentation zuerst als Orientierung und später als geprüften Betriebsstand. Aussagen werden nach tatsächlichen Tests aktualisiert; kein Handbuch behauptet einen erfolgreichen Restore, der nie durchgeführt wurde.

• Architekturhandbuch: Zweck, Systemkontext, Komponenten und Vertrauensgrenzen; Sequenzdiagramme für zentrale Abläufe; Datenmodell mit ERD. Bei einer Anwendung ohne persistentes Datenmodell wird dies ausdrücklich begründet.
• Benutzerhandbuch: Rollen, wichtigste Arbeitswege, erwartete Ergebnisse, verständliche Fehlermeldungen und Grenzen. Die Anleitung verwendet reale Oberflächenbezeichnungen.
• Entwicklerhandbuch: Projekt-Einstieg, lokale Einrichtung, Quellstruktur, Tests, AGENTS.md, Skills, Integration und Erweiterungswege. Neue Menschen und KI-Agenten finden den ersten sinnvollen Prüfpunkt.
• Betriebshandbuch: Installation, Konfiguration, Secrets, Daten, DNS/TLS/Proxy, Überwachung, Wartung, Sicherung, Restore, Updates, Migration und Rückweg. Es nennt Verantwortliche und verifizierte Nachweise.

Systemkontext zeigt, wer mit welchem System spricht. Ein Sequenzdiagramm erklärt die zeitliche Reihenfolge eines konkreten Ablaufs. Ein ERD zeigt Entitäten und Beziehungen. Die Diagramme beantworten unterschiedliche Fragen und werden aus dem tatsächlichen Projekt abgeleitet, nicht als dekorative Bilder ergänzt.

Im integrierten Browser lassen sich konkrete Elemente oder Textstellen annotieren. So erhält der Agent einen bestimmteren Bezug als bei «dies sieht komisch aus»: Element, sichtbarer Zustand und Dein Änderungswunsch stehen zusammen. Fenstergrösse, Sprache und erwartetes Verhalten ergänzen den Befund. Anschliessend wird die tatsächlich geänderte Oberfläche erneut geprüft. Funktionen und Unterstützung hängen von der Entwicklungsumgebung ab. OpenAI: Browser-Annotations.

10. Promptwerkstatt: direkt als Aufgabenstart verwenden

Ersetze die Platzhalter, prüfe den Umfang und sende nur den passenden Auftrag. Die Vorlagen enthalten keine versteckten Freigaben für fremde Systeme. Ein unklarer Zugang oder ein fehlender Nachweis wird zuerst geklärt.

Planung

Lies zuerst <PROJECT_ROOT>/AGENTS.md, Architektur und vorhandene Tests.
Ziel: <OBSERVABLE_GOAL>. Betroffene Nutzer: <AUDIENCE>.
Erfasse Ist-Zustand, Annahmen, Daten und Schnittstellen. Trenne Fakten von offenen Fragen.
Erstelle einen kleinen Umsetzungsplan mit Abhängigkeiten, Abnahmekriterien und passenden Nachweisen.
Grenzen: <EXCLUDED_CHANGES>. Noch keine Dateien ändern und nichts bereitstellen.
Frage nur nach Angaben, die den nächsten Schritt wesentlich verändern.

Umsetzung

Setze den freigegebenen Schritt <PLAN_STEP> für <WORK_ITEM> um.
Ausgangsstand: <BASE_COMMIT>. Besitz: <FILES_OR_MODULES>.
Prüfe zuerst Arbeitsbaum und fremde Änderungen; setze sie nicht zurück.
Verwende bestehende Komponenten und Zugriffsregeln. Ergänze einen sinnvollen Verhaltenstest.
Prüfe Diff und Ergebnis, aktualisiere betroffene Handbücher und melde Commit sowie echte Testnachweise.
Nicht freigegeben: <EXCLUDED_CHANGES>. Kein Merge oder Deployment ohne entsprechende Auftragsfreigabe.

Bugfixing mit Browser-Annotation

Reproduziere den annotierten Fehler <ANNOTATION_REFERENCE> unter <TEST_URL>.
Erwartet: <EXPECTED_BEHAVIOUR>. Beobachtet: <ACTUAL_BEHAVIOUR>.
Fenstergrösse und Sprache: <VIEWPORT_AND_LANGUAGE>.
Nutze den integrierten Browser, falls in dieser Umgebung verfügbar. Trenne Beobachtung und Ursachenhypothese.
Ergänze einen passenden Regressionstest und behebe die Ursache mit kleiner Änderung.
Prüfe die betroffene Stelle, Tastaturbedienung und einen angrenzenden Fall.
Verwende synthetische Daten; keine Passwörter oder Tokens in Ausgabe oder Screenshots.

Tests und Abnahme

Prüfe <FEATURE> am Commit <COMMIT> gegen <ACCEPTANCE_CRITERIA>.
Berücksichtige Gast, normales Mitglied und freigegebenen Benutzer, soweit diese Rollen existieren.
Prüfe auch direkte Datei-/API-Pfade und die relevante Darstellung im integrierten Browser.
Verwende isolierte Testdaten. Trenne Syntax, Verhalten, CI, Image und Live-Abnahme.
Berichte erfolgreiche, fehlgeschlagene und nicht ausgeführte Prüfungen mit Grenzen.
Erkläre einen fehlenden Nachweis; behaupte daraus keinen Erfolg.

Begrenzte Diagnose-Schleife

Bearbeite <DEFECT> in höchstens <MAX_ITERATIONS> Diagnose–Änderung–Test-Durchläufen.
Pro Durchlauf: eine begründete Hypothese, eine gezielte Änderung und ein passender Nachweis.
Wenn dieselbe Ursache zweimal ungeklärt bleibt, neue Risiken entstehen oder <STOP_CONDITION> eintritt:
Stand sichern, Schleife beenden und konkret fehlende Evidenz benennen.
Keine pauschalen Abschaltungen von Tests oder Schutzmechanismen. Kein Deployment in diesem Auftrag.
Aktualisiere <WORK_ITEM> mit Befund, Fortschritt und nächster Entscheidung.

Cloud-Zugang prüfen

Prüfe lesend, ob diese Ausführungsumgebung das private GitLab CE unter <GITLAB_HTTPS_URL> erreicht.
Erfasse verfügbare Netzwerk-/VPN-Funktionen, DNS, Route, TLS-Vertrauen, Authentisierung und Projektrechte.
Prüfe getrennt Git-SSH an <GIT_SSH_HOST>:<SSH_PORT> und Registry <REGISTRY_HTTPS_URL>.
Verifiziere SSH-Hostschlüssel gegen <VERIFIED_FINGERPRINT_SOURCE>; StrictHostKeyChecking bleibt aktiv.
HTTPS-Netzwerk-Secrets sind keine SSH-Schlüssel. Keine Rohsecrets anzeigen oder ins Repo kopieren.
Teste eine harmlose Leseoperation. Falls der Weg fehlt, dokumentiere die minimale benötigte Anbindung.
Keine öffentliche Freigabe, Firewalländerung oder Zertifikatsumgehung ohne Auftrag.
Wiederhole in der aktiven Agentenphase getrennt glab api, git ls-remote und authentifizierten Registry-Metadatenabruf.
Prüfe Registry-Host, Bearer-Auth-Realm und gegebenenfalls Blob-Hosts in der Netzwerkfreigabe.
Ein Setup-Login oder API-Header garantiert keine Git-Helper-/SSH-/Registry-Anmeldung. Keine echten Tokens in gecachte Konfiguration schreiben.

Fall A: Proxmox und Codex-Arbeitsordner

Übernimm <APPLICATION> auf Proxmox <PROXMOX_TARGET> geordnet in ein privates GitLab-CE-Projekt <DESTINATION_PROJECT>.
Quellhinweis: <EXACT_APPLICATION_FOLDER_UNDER_CODEX>. Kopiere niemals pauschal ~/.codex.
Phase 1 nur lesend: Ist-Betrieb, Quellherkunft, Symlinks, DB, persistente Dateien, Secrets und Netzwerk inventarisieren.
Lege Sicherung, Restore-Nachweis, Ziel-Gitwurzel und eine geprüfte Dateiauswahl fest.
Erstelle vor Änderungen den Ablauf mit Rückkehrkriterium <ROLLBACK_TRIGGER> und vier Handbuchgerüsten.
Nach freigegebener Übernahme: Baseline, private Remote, Tests und CI, Registry-Digest, Testbetrieb, Proxy/TLS und kontrollierter Cutover.
Erhalte Originale bis zur Abnahme. Markiere nicht geprüfte Schritte ausdrücklich.

Fall B: GitHub nach GitLab CE

Plane die Migration von <GITHUB_PROJECT> nach selbst betriebenem GitLab CE <DESTINATION_PROJECT>.
Erfasse Git-Referenzen, lokale Änderungen, LFS, Submodule sowie Issues/PRs/Reviews, Wiki, Releases/Dateien,
CI, Secrets/Variablen, Pakete/Registry, Webhooks, Integrationen, Rechte und Branch-Regeln.
Gib pro Bestand Importweg, erforderliche Rechte, Abgleich und Ersatzweg an.
Erhalte den bisherigen origin zunächst; kein blindes mirror-push in ein genutztes Ziel.
Übertrage keine Secrets in Git. Plane CI-Übersetzung und vermeide doppelte Deployment-Trigger.
Abnahme: frischer GitLab-Clone, Referenz-/Metadatenabgleich, Tests, Build und kontrollierter Arbeitswechsel.
Produktionsänderungen nur im separat freigegebenen Schritt.

Ein neues Projekt beginnen

Starte <PROJECT_NAME> für <AUDIENCE> mit Ziel <OBSERVABLE_GOAL>.
Arbeite ausschliesslich in <PROJECT_ROOT>; prüfe zunächst vorhandene Dateien und Git-Status.
Lege AGENTS.md, README, Secret-freie Beispielkonfiguration und die vier Handbuchgerüste an.
Erstelle eine kleine vertikale Funktion mit synthetischen Daten und sinnvoller Abnahme.
Plane ein privates Projekt auf <GITLAB_HTTPS_URL> im Namespace <NAMESPACE>.
Bevor CI/Deployment angebunden werden: Rechte, Runnervertrauen, Registry, Daten, Proxy/TLS und Rückweg klären.
Liefere kleine prüfbare Schritte statt einer ungetesteten Gesamtlösung.

CI/CD, Workitems und Fortschritt

Ordne <WORK_ITEM> dem Projekt <DESTINATION_PROJECT> auf dem eigenen GitLab CE zu.
Prüfe CLI-/Serverfähigkeiten und vorhandene CI, bevor Du Befehle oder Funktionen voraussetzt.
Trenne untrusted Prüfjobs, vertrauenswürdigen Build und Deployment; dokumentiere Docker-Socket-/Hostvertrauen.
Halte Commit, Pipeline, Job, Testberichte und Image-Digest zusammen. Cache ist keine Releasequelle.
Koordiniere Deployment mit <ENVIRONMENT> und <DEPLOYMENT_LOCK>; CE-Freigabefunktionen nicht pauschal annehmen.
Aktualisiere den Aufgabenstatus anhand wirklicher Nachweise. Fehlgeschlagen, blockiert und nicht geprüft bleiben unterscheidbar.

Bereitstellung, Proxy und TLS

Bereite die autorisierte Bereitstellung von <IMAGE_AT_DIGEST> auf <TARGET_HOST> unter <DEPLOYMENT_DIRECTORY> vor.
Prüfe den Registry-Pull vom Zielhost, Zielarchitektur, freien Speicher, Dienstbenutzer und geschützte Secrets.
Erfasse persistente DB-/Dateimounts. Sichere Daten und prüfe den Rückweg für Migration <MIGRATION_PLAN>.
Verwende vorhandenen Proxy <PROXY> und FQDN <APPLICATION_FQDN>; prüfe DNS, Netzwerk, Port und TLS.
Traefik-Labels müssen zum bestehenden Netz, Resolver und Dienstport passen.
Für Wildcard <CERTIFICATE_NAMES>: DNS-01-Berechtigung geschützt, Namensabdeckung und Erneuerung prüfen.
Koordiniere <DEPLOYMENT_LOCK>. Nach Umschalten: Health, Proxy/TLS, Anmeldung, Hauptfunktion, Persistenz und Version prüfen.
Bei <ROLLBACK_TRIGGER> bekannten betriebsfähigen Stand samt passender Daten wiederherstellen; nichts global bereinigen.

Vier gepflegte Handbücher

Führe die vier Handbücher für <PROJECT_ROOT> anhand des tatsächlichen Codes und der Nachweise <EVIDENCE_PATHS> nach.
Architektur: Kontext, Komponenten, Vertrauensgrenzen, zentrale Sequenzen und ERD des wirklichen Datenmodells.
Benutzer: Rollen, Hauptabläufe, Fehlerfälle und aktuelle Oberflächenbegriffe.
Entwickler: lokaler Einstieg, Regeln, Module, Tests und Erweiterungswege für Mensch und KI.
Betrieb: Installation, Konfiguration/Secrets, Proxy/TLS, Daten, Wartung, Sicherung/Restore, Migration und Rückweg.
Speichere Diagrammquellen versioniert und prüfe ihre Darstellung.
Kennzeichne Annahmen und nicht ausgeführte Restore-/Live-Prüfungen. Verlinke Aufgaben, Versionen und echte Belege.

Weiterlernen und anwenden

Spiele die Entscheidungen im Labor durch und vergleiche sie mit den beiden Fallsequenzen. Die Simulation führt keine echten Git-, Netzwerk- oder Deployment-Aktionen aus. Übertrage den Ablauf erst nach Prüfung auf Dein eigenes Projekt. Die Git-Präsentation vertieft Branches, Reviews und CI/CD.

Quellen geprüft am 19. Oktober 2026. Konkrete Fähigkeiten hängen von Produkt, Version, Lizenz und Umgebung ab. Fallsequenzen und Promptvorlagen sind unsere ECDA-Arbeitsweise; sie sind kein Nachweis, dass ein reales Zielsystem bereits migriert oder abgenommen wurde.