Git-Quellen und Build Worker

Konfigurieren Sie den Connector über Git-Hosting. Diese Anleitung trennt außerdem Repository-Berechtigungen von den Zielberechtigungen, die zum Starten gespeicherter Builds und zum Lesen ihres Verlaufs nötig sind. Registry-Zugangsdaten werden unter Container-Registries behandelt.

Die Unterstützung für Git-Quellen verbindet eine freigegebene Repository-Revision mit einem unveränderlichen Build-Artefakt. Sie kann einen Docker-Container, ein Deployment, ein Compose-Projekt oder ein Pages-Release beliefern, der resultierende Workload folgt aber weiterhin dem Lebenszyklus seiner zuständigen Ressource. Eine Quellverbindung ist für sich genommen keine Berechtigung, eine Produktionsroute oder ein Traffic-Ziel zu ändern.

Festlegen, was Automatisierung tun darf

Trennen Sie drei Entscheidungen: wer die Quelle lesen darf, was als freigegebenes Artefakt gilt und ob dieses Artefakt automatisch bereitgestellt werden darf. Diese Trennung erlaubt es einem Team, Routine-Releases zu automatisieren, ohne einem Repository-Webhook unbegrenzte Befugnis in der Produktion zu geben.

Der Quellverantwortliche steuert den Repository-Zugriff und den zu bauenden Commit. Der Plattformverantwortliche steuert Build Worker, Build-Richtlinie, Registry und Deployment-Ziel. Der Dienstverantwortliche legt Abnahme und Rollback fest. Opfield verbindet diese Einträge und bewahrt die Herkunft vom Commit bis zum Digest, aber ein erfolgreicher Build bleibt nur eine Eingabe für ein Release.

Verwenden Sie den automatischen Build, wenn jede ausgewählte Quelländerung ein Artefakt erzeugen soll. Aktivieren Sie das automatische Deployment erst, wenn die zuständige Ressource ein getestetes Health-Gate und einen Wiederherstellungsweg hat, und nur für Branches, deren Änderungskontrollmodell es erlaubt. Halten Sie bei Diensten mit höherem Risiko die Freigabe des Artefakts und das Deployment als getrennte menschliche Entscheidungen.

Voraussetzungen und Zuständigkeit

Verwenden Sie eine unterstützte Quellintegration von der Allowlist und autorisieren Sie nur den Repository-Zugriff, den der Build benötigt. Wählen Sie eine genaue Branch-Revision und bestätigen Sie dann, dass der zugewiesene dedizierte Build Worker online ist. Der Worker führt standardmäßig jeweils einen Build aus (Parallel jobs auf seiner Node-Seite, bis zu 16), verwendet isolierten BuildKit- und containerd-Zustand, wendet feste Ressourcenlimits an, verweigert unsichere Build-Berechtigungen und leert den Cache zwischen Jobs. Ein Build-Worker-Host benötigt systemd.

Eingereihte Builds gehen an Build Worker in der Reihenfolge, in der sie in der Liste Nodes erscheinen: Der erste Worker, der online ist, übernimmt Builds, bis alle seine parallelen Jobs belegt sind, dann übernimmt der nächste. Ziehen Sie einen Worker nach oben, um ihn zu bevorzugen, oder ganz nach unten, um ihn für Überlauf vorzuhalten. Die Reihenfolge der Liste sind Ordner auf oberster Ebene nach Position, innerhalb eines Ordners zuerst seine Unterordner und dann seine Nodes, und Nodes außerhalb eines Ordners zuletzt. Ein Worker übernimmt nur Builds für seine eigene Plattform (Architektur).

Build Secrets sind quellbezogen und werden während des Builds als Secrets eingebunden. Legen Sie keine Zugangsdaten in Build-Argumente, Image-Referenzen, Repository-URLs, eingecheckte Konfiguration oder Logs. Der Build Worker ist für die Isolation der Ausführung zuständig; die Registry hält das erzeugte Artefakt; der Ziel-Docker-Node bezieht und führt dieses Artefakt später aus.

Das Artefakt bauen und prüfen

1. Verbinden Sie die Integration und wählen Sie Repository, Branch und die vorgesehene Revision.
2. Konfigurieren Sie die Build-Eingabe und quellbezogene Secrets.
3. Starten Sie den Build und verfolgen Sie seinen Task von der Worker-Zuweisung bis zur Veröffentlichung des Artefakts.
4. Prüfen Sie geschwärzte Logs, Schwachstellenbefunde, das Richtlinienergebnis, den Quell-Commit und den unveränderlichen Artefakt-Digest.
5. Wählen Sie den freigegebenen Digest im Ablauf des zuständigen Containers, Deployments oder von Pages.

Während ein Build auf einen Container, ein Deployment oder ein Compose-Projekt ausgerollt wird, sperrt Opfield dieses Ziel: Lebenszyklus- und Konfigurationsänderungen, Secret-Änderungen, Availability-Änderungen und Migrationen werden mit BUILD_ROLLOUT_IN_PROGRESS abgelehnt, bis das Rollout erfolgreich ist, fehlschlägt oder abgebrochen wird, und die Konsole zeigt ein Banner am Ziel. Die Sperre übersteht einen Neustart von Opfield. Ist das Ziel beim Start des Rollouts mit einer anderen Operation beschäftigt, wartet das Rollout bis zu 5 Minuten und schlägt dann mit BUILD_ROLLOUT_TARGET_BUSY fehl. Pages-Releases werden auf diese Weise nicht gesperrt. Während eines Opfield-Updates werden Builds, die von Webhooks oder Polling ausgelöst werden, zurückgestellt und starten nach dem Update einmal.

Sync now an der Git-Quelle eines Containers, Deployments, Compose-Projekts oder Pages-Projekts prüft den Branch sofort und baut, wenn er sich bewegt hat und automatische Builds aktiviert sind. Die Schwachstellenrichtlinie der Quelle lehnt Artefakte mit Befunden ab, die mindestens den gewählten Schweregrad erreichen (standardmäßig Critical oder High, Medium oder Low); None gibt jedes gescannte Artefakt frei, und Disabled gibt Artefakte frei, ohne einen Scan zu verlangen. Build-Ergebnisse werden in die Registry übertragen, ohne im eigenen Image-Speicher des Workers zu bleiben, sodass Builds die Festplatte des Workers nicht füllen.

Automatischer Build und automatisches Deployment sind unabhängige Steuerungen. Lassen Sie das automatische Deployment deaktiviert, bis der Health- und Rollback-Weg für diesen Workload nachgewiesen ist. Ein erfolgreicher Build beweist nur, dass ein Artefakt existiert; er beweist nicht, dass die Anwendung auf einem Ziel-Node korrekt startet.

Ordnerplatzierung gebauter Workloads

Ein Container oder Deployment, das aus einer Git-Quelle erstellt wird, landet in dem Ordner, der beim Erstellen gewählt wurde: im Ordnerfeld der Registerkarte Repository des Deploy-Dialogs oder über folderId in der API und MCP. Das Erstellen dort erfordert die Erstellungsberechtigung für diesen Ordner, und ein Benutzer, der nur in Ordnern erstellen darf, muss einen wählen; der Dialog wählt den einzigen erlaubten Ordner vor. Das Konfigurieren der Quelle erfordert außerdem integrations:<provider>:use auf dem Repository; siehe Git-Hosting.

Bis sein erster Build abgeschlossen ist, wird der Workload in diesem Ordner mit Awaiting build anstelle eines Images aufgeführt. Er kann wie jeder andere Container verschoben werden: mit Move to folder…, per Ziehen oder über die API und MCP, was Bearbeitungsberechtigung für den Workload und das Ziel erfordert. Der erste Build erstellt ihn in dem Ordner, in dem er sich zu diesem Zeitpunkt befindet, und prüft dort die Erstellungsberechtigung, auch wenn die Quellautomatisierung den Build startet. Ein auf Ordner beschränkter Benutzer erhält daher nie einen gebauten Workload auf oberster Ebene. Der Name bleibt währenddessen für die Quelle reserviert: Das Erstellen, Duplizieren, Umbenennen oder Importieren eines anderen Containers unter diesem Namen schlägt mit 409 NAME_IN_USE fehl.

Fehlerbehandlung

Kann ein Build nicht starten, prüfen Sie Quellautorisierung, Verfügbarkeit des Workers, Leistungsumfang und Zustand der Integration. Builds verwenden die Zugangsdaten des Connectors und hängen nicht von den aktuellen Git-Scopes einer Person ab: integrations:<provider>:use auf dem Repository wird nur benötigt, um die Quelle zu verbinden oder ihren Connector, ihr Repository oder ihren Branch zu ändern; siehe Wer darf bauen und Ergebnisse ansehen?. Schlägt er nach dem Start fehl, verwenden Sie Phase und Logs, um Fehler bei Abhängigkeiten, Secrets, Richtlinie, Build-Definition oder Veröffentlichung des Artefakts zu unterscheiden. Korrigieren Sie die Quell- oder Build-Konfiguration und führen Sie dann einen neuen Build aus. Eine Wiederholung erzeugt eine neue Operation und bewahrt den vorherigen Verlauf.

Sind der Worker oder die Quellautomatisierung nicht verfügbar, bleibt der bestehende Verlauf für die Diagnose nützlich, aber es darf nicht angenommen werden, dass neue Builds laufen. Ersetzen Sie das fehlende unveränderliche Artefakt nicht durch einen veränderlichen Image-Tag; warten Sie auf einen geprüften Build oder verwenden Sie ein separat freigegebenes Image.

Bereitschaft nach einem Rollout

Wird ein Build auf einen Container ausgerollt, erstellt Opfield ihn mit dem neuen Image neu und wartet bis zu 60 Sekunden, bis er bereit ist: fehlerfrei, wenn das Image einen Health Check hat, andernfalls 10 Sekunden lang ohne Neustart laufend. Ein Container, der in einer Absturzschleife hängt, beendet wird oder fehlerhaft wird, wird auf sein vorheriges Image zurückgesetzt, und der Build schlägt mit BUILD_ROLLOUT_ROLLED_BACK fehl, oder mit BUILD_ROLLOUT_ROLLBACK_FAILED, wenn das vorherige Image nicht wiederhergestellt werden konnte. Der Fehler nennt den Containerzustand, den Exit-Code und die Anzahl der Neustarts, gefolgt von den letzten Zeilen seines Logs, und der bereitgestellte Commit bleibt der vorherige. Andere Rollout-Fehler werden als BUILD_ROLLOUT_FAILED gemeldet. Ein Deployment verwendet seinen eigenen Blue/Green-Weg mit Health Checks: Ein fehlschlagender Kandidat wird gestoppt, und der Datenverkehr bleibt auf dem bedienenden Slot. Eine aus Git gebaute Compose-Revision, deren veröffentlichten Port auf dem Node bereits ein anderer Workload belegt, schlägt mit COMPOSE_HOST_PORT_IN_USE fehl, und es wird keine Revision erstellt.

Bereinigung und Rollback

Das Entfernen einer Quellverbindung verhindert künftige quellgesteuerte Arbeit, löscht aber eine bereits bereitgestellte Laufzeit oder ihr Artefakt nicht automatisch. Das Entfernen eines Containers entfernt seine Git-Quelle, und wenn der Repository-Webhook eines entfernten Containers nicht gelöscht werden kann, hört seine Quelle auf zu bauen und bereitzustellen, sodass ein neuer Commit den Container nicht neu erstellen kann; die Bereinigung wird später wiederholt. Build-Images gelöschter Container, Deployments und Compose-Projekte werden automatisch von ihren Nodes entfernt, meist innerhalb einer Minute, und Nodes, die offline waren, werden alle 10 Minuten erneut geprüft. Ein nicht verwendetes Build-Image kann auch manuell aus den Images des Nodes entfernt werden; eines, das ein Container auf dem Node noch verwendet, wird mit 409 OPFIELD_INTERNAL_IMAGE abgelehnt. Entscheiden Sie vor dem Widerruf der Verbindung, welche Artefakte für ein Rollback erforderlich bleiben. Die Aufbewahrung von Artefakten richtet sich nach der Registry und dem Verlauf der zuständigen Ressource aus aktiven, Rollback-, laufenden, angehefteten und kürzlich erfolgreichen Einträgen.

Erfolgskriterien

Ein akzeptabler Build identifiziert das Repository und den genauen Commit, wird auf einem freigegebenen Worker abgeschlossen, erzeugt einen unveränderlichen Digest, besteht die konfigurierte Schwachstellenrichtlinie und stellt Logs ohne Secrets bereit. Die Abnahme des Deployments ist getrennt: Die Zielressource muss diesen Digest beziehen, erfolgreich starten, die Health-Prüfung bestehen und den erwarteten Client-Pfad bedienen.

Bewahren Sie genug Build- und Artefaktverlauf auf, um zu erklären, was läuft, und um das vorherige bekannt fehlerfreie Release wiederherzustellen. Ein veränderlicher Tag, ein erfolgreiches Konsolenlog oder ein grünes Build-Abzeichen ohne Digest ist kein ausreichender Produktionsbeleg.

Details für Betreiber: Isolation und Diagnose

Build Worker sind dedizierte Ausführungsgrenzen, weil Repository-Inhalte und Build-Definitionen Code ausführen können. Halten Sie die Zugangsdaten des Workers eng, platzieren Sie keine fremden sensiblen Workloads auf demselben Host und behandeln Sie Build-Ausgaben als nicht vertrauenswürdig, bis Richtlinien- und Herkunftsprüfungen abgeschlossen sind. Build Secrets sollten nur für den Build-Schritt eingebunden werden, der sie benötigt, und dürfen nicht in Image-Schichten kopiert werden.

Build-Schritte können den Build-Worker-Host selbst nicht erreichen, weder über IPv4 noch über IPv6, mit keinem der beiden Egress-Profile (internet oder offline). Auf einem Host mit IPv6 benötigt der Worker ip6tables und startet ohne es nicht.

Wenn ein Build eingereiht ist, unterscheiden Sie fehlende Worker-Kapazität von einem Quell- oder Richtlinienfehler. Wenn er läuft und fehlschlägt, ermitteln Sie die Phase: Checkout der Quelle, Auflösen von Abhängigkeiten, Dockerfile- oder Compose-Build, Schwachstellenzulassung, Veröffentlichung in der Registry oder abschließende Bestätigung. Bewahren Sie das begrenzte Log und den Commit, bevor Sie es erneut versuchen. Eine Wiederholung sollte einen neuen nachvollziehbaren Versuch erzeugen, statt den fehlgeschlagenen Eintrag zu überschreiben.