Git Deploy verbindet ein Repository mit einer Website, sodass jeder Push auf den gewählten Branch den Code klont, Ihren Build ausführt und das Ergebnis veröffentlicht. Diese Anleitung behandelt die Erstverbindung, die beiden Schritte auf Repository-Seite, die das Setup abschließen, das Auslesen des Bereitstellungsverlaufs und die Buildpack-Erkennung, die bestimmt, wie eine Node.js-App gebaut wird.
Wo Sie Git Deploy Finden
Öffnen Sie Websites, klicken Sie auf die Website, öffnen Sie die Gruppe Environment im linken Menü der Website, und wählen Sie Git-Deploy. Zwei verwandte Seiten befinden sich in der Nähe:
- Deployments, der vollständige Bereitstellungsverlauf für diese Website, in derselben Gruppe Environment.
- Buildpack, die erkannte Build-Strategie, bei Node.js-Websites, in der Gruppe Apps.
Die Seite Git Deploy beschreibt sich selbst unmissverständlich: Verbinden Sie ein Repository, und jeder Push auf Ihren konfigurierten Branch löst einen Build und ein Deployment aus.
Ein Repository Verbinden
- Wählen Sie Ihren Provider: GitHub, GitLab oder Bitbucket.
- Geben Sie die Repository-URL ein. Die SSH-Form ist die gewünschte, zum Beispiel
git@github.com:user/repo.git. - Legen Sie den Branch fest, von dem aus bereitgestellt werden soll. Das Feld beginnt bei
main. - Optional können Sie einen Build-Befehl festlegen, zum Beispiel
npm run build. - Optional können Sie ein Ausgabeverzeichnis festlegen, zum Beispiel
dist,publicoder.für ein Repository, das bereits gebaut ist. - Klicken Sie auf Repository verbinden.
Lassen Sie Build-Befehl und Ausgabeverzeichnis leer, wenn Ihr Repository bereits so, wie es ist, bereitstellbar ist, was bei einer einfachen PHP- oder statischen Website der Regelfall ist.
Erweiterte Skripte
Durch Aufklappen von Erweitert erscheinen zwei zusätzliche Felder:
- Pre-Deploy-Skript, das vor dem Build ausgeführt wird.
- Post-Deploy-Skript, das nach dem Deployment ausgeführt wird.
Nutzen Sie den Post-Deploy-Hook für Dinge, die geschehen müssen, sobald der neue Code vorhanden ist: das Leeren eines Anwendungs-Caches, das Ausführen einer Datenbankmigration, das Neustarten eines Workers.
Automatisches Deployment Bei Push
Der Schalter am unteren Rand der Karte steuert, ob Pushes überhaupt ein Deployment auslösen. Ist er aktiviert, löst jeder Push auf den konfigurierten Branch ein Deployment aus. Ist er deaktiviert, laufen Deployments nur, wenn Sie sie manuell über Jetzt bereitstellen auslösen.
Schalten Sie das automatische Deployment während eines Code-Freezes oder eines Vorfalls lieber ab, statt das Repository zu trennen. Durch das Trennen werden der Deploy-Schlüssel und das Webhook-Secret verworfen, sodass Sie anschließend beide Schritte auf Repository-Seite erneut durchführen müssen.
Das Setup In Ihrem Repository Abschliessen
Das Verbinden des Repositorys in KPanel ist nur der erste von drei Schritten. Solange noch kein Deployment gelaufen ist, zeigt die Seite ein Banner mit der Aufschrift Setup abschließen: 2 Schritte verbleibend mit allem, was Sie benötigen.
Schritt 2: Deploy-Schlüssel Hinzufügen
KapsuleHost benötigt Lesezugriff, um Ihr Repository zu klonen. Das Banner zeigt einen öffentlichen Schlüssel mit einer Schaltfläche Schlüssel kopieren.
Fügen Sie ihn in die Deploy-Schlüssel Ihres Repositorys ein. Für GitHub bietet das Banner die Abkürzung Zu GitHub hinzufügen direkt zur passenden Einstellungsseite. Lesezugriff genügt, gewähren Sie keinen Schreibzugriff.
Schritt 3: Webhook Hinzufügen
Der Webhook teilt KapsuleHost mit, dass ein Push stattgefunden hat. Das Banner liefert Ihnen drei Werte:
| Feld | Wert |
|---|---|
| Payload-URL | Eine URL, die auf /api/git-deploy/webhook/ plus die ID dieser Website endet |
| Secret | Ein generiertes Signatur-Secret, verborgen, bis Sie auf das Augensymbol klicken |
| Content-Type | application/json |
Kopieren Sie jeden Wert in die Webhook-Einstellungen Ihres Repositorys. Für GitHub gibt es die Abkürzung Webhook zu GitHub hinzufügen. Stellen Sie den Content-Type auf JSON, nicht auf den formularkodierten Standard, sonst lässt sich die Payload nicht parsen.
Behandeln Sie das Webhook-Secret wie ein Passwort. Wer es besitzt, zusammen mit der Payload-URL, kann ein Deployment Ihrer Website auslösen. Beide Werte werden nur Personen angezeigt, die die Website bereits verwalten dürfen, und das Secret bleibt hinter dem Augensymbol verborgen, bis Sie es anfordern.
Manuell Bereitstellen
Klicken Sie auf der Git-Deploy-Seite auf Jetzt bereitstellen, um den aktuellen Stand des konfigurierten Branches zu bauen und bereitzustellen, ohne einen Commit zu pushen. Dies funktioniert unabhängig davon, ob das automatische Deployment aktiviert ist, und macht die Funktion zum richtigen Werkzeug während eines Freezes: Pushes werden ignoriert, aber Sie können den Fix trotzdem ausliefern.
Den Bereitstellungsverlauf Lesen
Öffnen Sie Environment, dann Deployments. Die Seite trägt den Titel Bereitstellungsverlauf und listet jedes durch Webhook oder manuell ausgelöste Deployment auf, neueste zuerst.
Jede Zeile enthält:
- Ein Statussymbol und die kurze Commit-SHA, mit dem Branch als Pille.
- Die Commit-Nachricht, oder Manuelles Deployment, falls keine Commit-Nachricht vorhanden war.
- Den Autor, wie lange es her ist, wie lange es gedauert hat, und was es ausgelöst hat.
- Eine Status-Pille.
Die Status sind pending, building, deploying, success und failed. Solange etwas läuft, aktualisiert sich die Seite alle fünf Sekunden selbst und zeigt unter der Tabelle den Hinweis Refreshing automatically, sodass Sie sie geöffnet lassen und ein Deployment live mitverfolgen können.
Wenn Ein Deployment Fehlschlägt
Eine fehlgeschlagene Zeile erhält rechts eine Schaltfläche Error. Klicken Sie darauf, um die erfasste Fehlerausgabe inline aufzuklappen, ohne die Seite zu verlassen. Diese Ausgabe ist der eigene Fehlertext des Builds, daher nennt er meist die Datei oder den Befehl, der fehlgeschlagen ist.
Gehen Sie in dieser Reihenfolge vor: Fehler lesen, denselben Build-Befehl lokal reproduzieren, beheben, pushen. Wenn der Build lokal funktioniert, hier aber nicht, liegt der Unterschied fast immer an der Umgebung, etwa einer Abhängigkeit, die auf Ihrem Rechner global installiert ist, oder einer Datei, die sich in Ihrem Arbeitsverzeichnis befindet, aber nicht committet wurde.
Buildpack-Erkennung
Bei Node.js-Websites zeigt die Seite Buildpack in der Gruppe Apps, wie KapsuleHost entschieden hat, Ihre App zu bauen. Die Erkennung läuft über die Dateien im Wurzelverzeichnis Ihres Repositorys, und der erste Treffer gewinnt:
| Erkannt | Auslöser |
|---|---|
| Individuelles Buildpack | kapsule.config.yaml oder kapsule.config.yml im Wurzelverzeichnis |
| Dockerfile-Buildpack | Dockerfile im Wurzelverzeichnis |
| Node.js | package.json mit einem start-, build- oder dev-Skript |
| Python | requirements.txt oder pyproject.toml |
| PHP | composer.json |
| Statisch | index.html im Wurzelverzeichnis |
Trifft nichts zu, meldet die Seite dies und listet die unterstützten Auslöser auf. Fügen Sie ein Dockerfile oder ein kapsule.config.yaml hinzu, um die Kontrolle über den Build ausdrücklich zu übernehmen.
Einen Build Ausführen
Klicken Sie auf Build ausführen, um einen Build einzureihen. Die Seite fragt alle drei Sekunden ab, während ein Lauf aktiv ist, und die Tabelle Letzte Builds zeigt die letzten Läufe mit Startzeit, Typ, Status, Dauer und resultierender Image-Referenz. Klicken Sie auf eine Zeile, um das Ende des Logs zu sehen.
Es kann immer nur ein Build gleichzeitig laufen. Das Auslösen eines zweiten, während einer eingereiht ist oder läuft, wird mit Ein Build ist bereits in Bearbeitung abgelehnt, was Absicht ist: Zwei Builds, die gleichzeitig dieselbe Ausgabe schreiben, sind der Weg zu einer halb bereitgestellten Website.
Trennen
Klicken Sie auf Disconnect und bestätigen Sie. Die Bestätigung ist eindeutig hinsichtlich der Auswirkungen: Die Git-Deploy-Konfiguration und der Deploy-Schlüssel werden entfernt, und Ihre Website-Dateien sind nicht betroffen. Die Website liefert weiterhin das zuletzt bereitgestellte Ergebnis aus.
Räumen Sie anschließend auf, indem Sie den Deploy-Schlüssel und den Webhook in Ihren Repository-Einstellungen löschen. Sie funktionieren danach einfach nicht mehr, aber verwaiste Einträge erschweren die nächste Prüfung.
Fehlerbehebung
Pushes lösen nichts aus. Prüfen Sie zuerst den Schalter für automatisches Deployment, dann den Webhook in Ihrem Repository. Die meisten Anbieter zeigen die letzten Zustellungen und deren Antwortcodes, was Ihnen sofort verrät, ob die Anfrage Ihr Repository überhaupt verlassen hat.
Das Klonen schlägt fehl. Der Deploy-Schlüssel fehlt, wurde mit einem Zeilenumbruch eingefügt oder wurde dem falschen Repository hinzugefügt. Kopieren Sie ihn erneut über die Schaltfläche Schlüssel kopieren, statt den Text von Hand zu markieren.
Das Deployment ist erfolgreich, aber die Website ändert sich nicht. Das Ausgabeverzeichnis ist vermutlich falsch. Wenn Ihr Build nach dist schreibt und das Ausgabeverzeichnis leer ist, erreichen die gebauten Dateien nie die ausgelieferte Wurzel.
Alles zeigt pending und bewegt sich nie. Das Deployment wurde eingereiht, aber nie aufgenommen. Lösen Sie ein manuelles Jetzt bereitstellen aus und prüfen Sie die Seite Deploys auf eine Fehlerzeile.
Wie Es Weitergeht
- Vorschau-Deployments für Pull Requests fügt diesem Setup eine URL pro Pull Request hinzu.
- App-Geheimnisse für eine Website Speichern für die Zugangsdaten, die Ihr Build und Ihre Laufzeitumgebung benötigen.
- Aktivitätsprotokoll der Website zeichnet hier vorgenommene Konfigurationsänderungen auf.