Preview-Deployments geben jedem Pull Request eine eigene Live-URL, erstellt aus dem Code dieses Branches, sodass Prüfer durch die tatsächliche Änderung klicken können, anstatt ein Diff zu lesen und zu raten. Jede Preview wird aktualisiert, wenn Sie einen neuen Commit pushen, und automatisch aufgeräumt, wenn der Pull Request geschlossen wird.
Wo Preview-Deployments zu finden sind
Öffnen Sie Websites, klicken Sie auf die Website, öffnen Sie die Gruppe Environment im linken Menü der Website und wählen Sie Vorschau. Die Seite trägt den Titel Preview-Deployments.
Previews sind von Staging getrennt. Staging ist eine dauerhaft bestehende Kopie der Website, die Sie bewusst aktualisieren; eine Preview ist eine kurzlebige Umgebung, die pro Pull Request erstellt und danach verworfen wird. Viele Teams nutzen beides. Die andere Hälfte finden Sie unter Staging-Umgebungen.
Git-Deployment zuerst einrichten
Previews sind kein eigenständiges Feature. Sie verwenden den Deploy-Key und den Build-Befehl der Produktionswebsite wieder, daher benötigt die Website eine funktionierende Git-Deployment-Konfiguration, bevor Previews aktiviert werden können.
Wenn Git-Deployment nicht konfiguriert ist, zeigt die Seite Git-Deployment zuerst einrichten an und bietet statt des Aktivierungsformulars eine Schaltfläche Zu Git-Deployment an. Arbeiten Sie Eine Website aus Git bereitstellen durch und kommen Sie dann zurück.
Wenn Git-Deployment verbunden ist, aber keinen Build-Befehl hat, zeigt die Preview-Seite eine Warnung an. Previews gehen dann davon aus, dass das Repository bereits gebaut ist und sich die statischen Dateien im Stammverzeichnis befinden. Das ist bei einer reinen HTML-Website korrekt, aber falsch bei allem, was kompiliert werden muss. Legen Sie daher auf der Git-Deployment-Seite einen Build-Befehl fest, falls Ihr Projekt einen benötigt.
Previews aktivieren
- Geben Sie im Feld Preview-Deployments aktivieren das Repository im Format
owner/repoein. Keine URL, keine SSH-Adresse: nur die zwei Segmente, zum Beispielacme/marketing-site. - Klicken Sie auf Aktivieren.
Alles, was nicht dem Format owner/name entspricht, wird mit der Meldung Repository muss im Format owner/name vorliegen abgelehnt.
Unmittelbar nach der Aktivierung zeigt KPanel das Webhook-Signing-Secret in einem Feld mit der Überschrift Kopieren Sie jetzt Ihr Webhook-Secret an, mit dem Hinweis, dass Sie es danach nicht mehr sehen werden.
Kopieren Sie das Secret, bevor Sie die Seite verlassen. Es wird einmalig erzeugt und ist danach nicht mehr abrufbar. Wenn Sie es verlieren, besteht die Lösung darin, es neu zu generieren, was das alte ungültig macht und bedeutet, dass Sie ohnehin den Webhook in Ihrem Repository aktualisieren müssen.
Den Webhook zu Ihrem Repository hinzufügen
Das konfigurierte Feld zeigt eine Webhook-URL an, die Sie in Ihre Repository-Einstellungen unter Webhooks einfügen. Konfigurieren Sie ihn mit:
- Payload-URL: die auf der Seite angezeigte Webhook-URL.
- Secret: der eben kopierte Wert.
- Inhaltstyp: JSON.
- Ereignisse: Pull-Request-Ereignisse sowie Pushes, damit neue Commits auf einem offenen Pull Request die Preview neu aufbauen.
Sobald das eingerichtet ist, wird beim Öffnen eines Pull Requests innerhalb weniger Minuten eine Preview gebaut. Ein Hintergrundjob prüft jede Minute auf neue Preview-Arbeiten, sodass in KPanel nichts gedrückt werden muss.
Preview-URLs
Jede Preview erhält einen eigenen Hostnamen in der Form pr-<pull-request-number>-<site-id>.kapsulecloud.app, abgedeckt durch ein Wildcard-Zertifikat, sodass sie über HTTPS ausgeliefert wird, ohne dass Sie selbst ein Zertifikat einrichten müssen.
Der zuverlässige Weg, eine Preview zu öffnen, ist die Schaltfläche Öffnen in der Zeile der Preview unter Aktuelle Previews, die genau die URL enthält, die für diesen Build bereitgestellt wurde. Fügen Sie diesen Link in den Pull Request ein, damit Prüfer KPanel überhaupt nicht finden müssen.
Die Liste der aktuellen Previews lesen
Der Abschnitt Aktuelle Previews listet die neuesten Previews zuerst auf. Jede Zeile zeigt die Pull-Request-Nummer und den Titel, den Branch, den Commit und einen Status:
| Status | Bedeutung |
|---|---|
| BUILDING | Wird gerade geklont und gebaut |
| LIVE | Wird unter seiner Preview-URL ausgeliefert |
| FAILED | Der Build ist fehlgeschlagen; Log aufklappen, um den Grund zu sehen |
| DESTROYED | Aufgeräumt, meist weil der Pull Request geschlossen wurde |
Klicken Sie auf Build-Log umschalten in einer Zeile, um deren Build-Ausgabe direkt anzuzeigen. Dieses Log ist die erste Anlaufstelle, wenn eine Preview fehlschlägt, und es zeigt dieselbe Ausgabe, die Ihr Build auch lokal erzeugen würde.
Wenn die Liste leer ist, weist die Seite darauf hin: Öffnen Sie einen Pull Request im Repository, und innerhalb weniger Minuten wird eine Preview gebaut.
Das Webhook-Secret rotieren
Klicken Sie im konfigurierten Feld auf Secret neu generieren. KPanel bittet um eine Bestätigung und weist ausdrücklich darauf hin, dass das aktuelle Secret sofort aufhört zu funktionieren und Sie es anschließend in den Webhook-Einstellungen Ihres Repositorys aktualisieren müssen.
Das neue Secret wird einmalig angezeigt, im selben einmaligen Feld wie zuvor. Kopieren Sie es und aktualisieren Sie dann den Webhook in Ihrem Repository. Zwischen diesen beiden Momenten werden eingehende Webhook-Zustellungen abgelehnt, führen Sie die beiden Schritte also unmittelbar nacheinander aus.
Generieren Sie das Secret neu, wenn jemand mit Admin-Zugriff auf das Repository das Team verlässt oder wenn das Secret jemals irgendwo eingefügt wurde, wo es nicht hingehört, etwa in einem geteilten Chat-Kanal oder einem Ticket.
Previews ausschalten
Klicken Sie auf Deaktivieren. Die Konfiguration wird abgeschaltet und das gespeicherte Secret wird gelöscht. Bestehende Previews werden nicht mehr neu gebaut.
Räumen Sie zusätzlich auf, indem Sie auch den Webhook in Ihrem Repository löschen. Er beginnt sonst, Fehler zu melden, statt Schaden anzurichten, aber ein Webhook, der dauerhaft Fehler zurückgibt, ist Lärm im Zustellungsprotokoll Ihres Repositorys.
Kosten und Pflege
Previews bauen und liefern echten Code aus, daher verbrauchen sie dieselben Ressourcen wie jedes andere Deployment auf der Website. Zwei Gewohnheiten halten das unter Kontrolle:
- Schließen Sie Pull Requests, an denen Sie nicht mehr arbeiten. Bei einem geschlossenen Pull Request wird die zugehörige Preview automatisch aufgeräumt.
- Verweisen Sie Previews nicht auf Produktionsanmeldedaten. Geben Sie ihnen Test-Keys über die Umgebung preview im Tab Secrets, die genau zu diesem Zweck existiert, damit Preview- und Produktionskonfiguration nicht verwechselt werden können.
Eine Preview-URL ist nicht privat. Es ist ein echter, öffentlich erreichbarer Hostname mit einem gültigen Zertifikat, und jeder, der den Link hat, kann ihn öffnen. Verwenden Sie eine Preview nicht, um etwas zu überprüfen, das echte Kundendaten enthält, und befüllen Sie Preview-Umgebungen nicht aus einem Produktionsdatenbank-Dump.
Fehlerbehebung
Es wird nichts gebaut, wenn ein Pull Request geöffnet wird. Prüfen Sie die letzten Zustellungen des Webhooks in Ihrem Repository. Ein 401 oder 403 bedeutet, dass das Secret nicht übereinstimmt; generieren Sie es neu und aktualisieren Sie beide Seiten. Keine Zustellung bedeutet, dass der Webhook nicht für Pull-Request-Ereignisse abonniert ist.
Die Preview wird gebaut, zeigt aber eine Verzeichnisliste oder einen 404-Fehler. Das Ausgabeverzeichnis auf der Git-Deployment-Seite stimmt nicht mit dem Ort überein, an den Ihr Build tatsächlich schreibt. Previews übernehmen diese Einstellung von der Produktion.
Der Build schlägt nur in der Preview fehl. Die häufigste Ursache ist eine Abhängigkeit oder eine Umgebungsvariable, die in der Produktion vorhanden ist, aber nie zur Preview-Umgebung hinzugefügt wurde. Prüfen Sie den Tab preview auf der Secrets-Seite.
Eine Preview-URL funktioniert nicht mehr. Sehen Sie sich den Status in der zugehörigen Zeile an. DESTROYED bedeutet, dass der Pull Request geschlossen und die Umgebung zurückgefordert wurde, was dem beabsichtigten Verhalten entspricht.
Wie es weitergeht
- Eine Website aus Git bereitstellen, die Voraussetzung an Konfiguration.
- App-Secrets für eine Website speichern für Anmeldedaten pro Umgebung.
- Staging-Umgebungen für eine dauerhafte Pre-Production-Kopie.