Orbit
Bereitstellungen über Deploy Hooks auslösen
A deploy hook is a secret URL that queues a new deployment when something sends it an HTTP POST. There is no authentication header: the secrecy of the URL is the authentication. Use hooks to let a…
Deploy-Hooks zum Auslösen von Bereitstellungen
Ein Deploy-Hook ist eine geheime URL, die eine neue Bereitstellung in die Warteschlange einreiht, wenn etwas eine HTTP POST an sie sendet. Es gibt keinen Authentifizierungs-Header: Die Geheimhaltung der URL ist die Authentifizierung. Verwenden Sie Hooks, um ein Headless-CMS, einen Cron-Job, eine CI-Pipeline oder einen beliebigen anderen Webhook zum Neuaufbau Ihres Projekts ohne Git-Push zu ermöglichen.
Deploy-Hooks finden
Hooks haben ihre eigene Registerkarte: Öffnen Sie Ihr Projekt in Orbit und klicken Sie auf Hooks, unter /orbit/<project-id>/hooks.
Die gleiche Registerkarte Deploy hooks erscheint auch in der Mitte der Registerkarte Settings Ihres Projekts, sodass Sie sie von beiden Stellen aus verwalten können.
Einen Deploy-Hook erstellen
- Öffnen Sie Orbit, dann Ihr Projekt, dann Hooks.
- Klicken Sie auf Add deploy hook.
- Geben Sie einen Hook name ein, der in sechs Monaten noch Sinn macht. Der Platzhalter deutet das Format an: „Contentful publish", „Nightly cron".
- Wählen Sie eine Target environment. Die Standardeinstellung ist Production (default). Wenn Ihr Projekt eine Staging-Umgebung hat, können Sie den Hook stattdessen auf Staging verweisen.
- Klicken Sie auf Create hook.
Der Hook erscheint in der Liste mit seiner URL, einer Schaltfläche Copy URL und einer Schaltfläche Delete hook.
Die Hook-URL
Hook-URLs sehen so aus:
https://kpanel.kapsulehost.com/api/orbit/hooks/<token>
Das Token ist ein eindeutiger Secret, der beim Erstellen des Hooks generiert wird.
Behandeln Sie eine Hook-URL genau wie einen API-Schlüssel. Jeder, der sie hat, kann eine Bereitstellung Ihres Projekts auslösen, und keine der Deploy-Gates von Orbit hält sie auf: Deploy-Sperren, erforderliche Genehmigung, CI-erforderliche Überprüfungen und erforderlicher Staging-Erfolg gelten nur für Push-ausgelöste Bereitstellungen, und ein Hook geht direkt durch. Fügen Sie eine Hook-URL niemals in ein öffentliches Repository, ein gemeinsames Dokument, einen Screenshot oder ein Support-Ticket ein.
Einen Hook auslösen
Senden Sie eine POST-Anfrage. Kein Body und keine Header sind erforderlich.
curl -X POST \
https://kpanel.kapsulehost.com/api/orbit/hooks/<your-token>
Orbit antwortet mit HTTP 202 und der Bereitstellungs-ID. Die Bereitstellung erscheint innerhalb weniger Sekunden auf der Registerkarte Deployments.
Der Endpoint akzeptiert nur POST. Eine GET-Anfrage löst keine Bereitstellung aus. Einige ältere Webhook-Integrationen verwenden standardmäßig GET, überprüfen Sie also die Methode, wenn ein konfigurierter Hook nie ausgelöst wird.
Was ein Hook tatsächlich bereitstellt
Der Hook löst seine Zielumgebung auf (die, die Sie gewählt haben, oder die Produktionsumgebung des Projekts), liest den Branch dieser Umgebung und fragt Ihren Git-Provider nach dem aktuellen Head-Commit dieses Branches. Dann reiht er eine Bereitstellung dieses Commits in die Warteschlange ein.
Das hat drei Konsequenzen, die es wert sind, bekannt zu sein:
- Ein Hook stellt immer den Branch-Head bereit. Sie können keine Commit-SHA oder einen Branch-Namen im Request-Body übergeben; der Request-Body wird vollständig ignoriert.
- Ein Hook benötigt eine funktionierende Provider-Verbindung. Wenn Sie GitHub, GitLab oder Bitbucket getrennt haben, kann der Hook den Branch-Head nicht lesen und schlägt mit einem Fehler fehl, anstatt veralteten Code bereitzustellen.
- Ein Hook führt den vollständigen Build erneut durch. Es ist kein Rollback und keine Promotion; es ist ein frischer Build von dem, was sich derzeit auf dem Branch befindet.
Wiederholte und überlappende Aufrufe
Orbit behandelt Bursts von Hook-Aufrufen sinnvoll, anstatt für jeden einen Build in die Warteschlange einzureihen.
- Wenn eine Bereitstellung für denselben Commit bereits auf dieser Umgebung läuft, gibt der Hook die vorhandene Bereitstellung zurück und kennzeichnet die Antwort als dedupliziert. Kein zweiter Build wird gestartet.
- Wenn ein Build für einen anderen Commit auf dieser Umgebung läuft, wird er automatisch abgebrochen und durch den neuen ersetzt, sodass Sie nicht für einen Build zahlen müssen, dessen Ausgabe bereits überholt ist.
Dies macht Hooks sicher für ein CMS, das einen Webhook pro veröffentlichtem Eintrag auslöst. Das Veröffentlichen von sechs Seiten in einer Minute erzeugt einen Build, nicht sechs, und verbraucht nicht sechs Builds' wert an Minuten.
Ein Headless-CMS verbinden
Die meisten Headless-CMSs haben eine Funktion „Webhook on publish". Das Muster ist immer das Gleiche: Verweisen Sie den Webhook auf Ihre Orbit-Hook-URL, verwenden Sie POST und lassen Sie die Authentifizierungseinstellungen leer.
Contentful
- Gehen Sie zu Settings, dann Webhooks, dann Add webhook.
- Stellen Sie die URL auf Ihre Orbit-Hook-URL ein.
- Stellen Sie die Methode auf POST.
- Stellen Sie den Trigger auf Publish oder auf welche Content-Events die Site neu aufbauen sollen.
- Speichern.
Sanity
Gehen Sie in Ihrem Projekt-Dashboard zu API, dann Webhooks, dann Create webhook. Stellen Sie die URL auf Ihre Hook-URL, die Methode auf POST ein und wählen Sie den Datensatz und die Triggerereignisse.
Prismic
Gehen Sie im Dashboard zu Settings, dann Webhooks, und fügen Sie Ihre Hook-URL hinzu. Prismic ruft sie bei jedem Dokument-Publish auf.
Einen Cron-Job oder eine CI-Pipeline verbinden
Jeder Scheduler, der eine HTTP-Anfrage stellen kann, funktioniert:
# crontab: rebuild every night at 2am
0 2 * * * curl -fsS -X POST https://kpanel.kapsulehost.com/api/orbit/hooks/<your-token>
Für CI ist ein Deploy-Hook die einfachste Option, wenn Ihre Pipeline entscheiden soll, ob eine Bereitstellung stattfindet. Es ist der empfohlene Ansatz für Bitbucket Pipelines, da die Einstellung „CI erforderliche Überprüfungen" von Orbit auf GitHub Actions Job-Namen oder eine GitLab-Pipeline abgrenzt, nicht auf Bitbucket.
Wenn Sie mehr als „den Branch-Head bereitstellen" benötigen, verwenden Sie ein API-Token statt eines Hooks. Orbit, dann Tokens, erstellt scoped Bearer-Tokens für CI/CD mit einer dokumentierten REST-API und einem vorgefertigten GitHub Actions-Workflow. API-Zugriff ist im Apex-Plan enthalten.
Ohne Hook auf einen Zeitplan neu aufbauen
Wenn Sie nur einen regelmäßigen Rebuild möchten, benötigen Sie überhaupt keinen Hook. Scheduled rebuild in Settings, unter Runtime, erstellt die Produktion automatisch jede Stunde, alle 6 Stunden, alle 12 Stunden, täglich, alle 2 Tage oder wöchentlich neu. Es wurde genau für den CMS-driven-site-Fall entwickelt und es gibt keine geheime URL zum Schützen.
Hook-Aktivität überprüfen
Jede Hook-Zeile zeigt, wie oft sie verwendet wurde und wann sie zuletzt verwendet wurde, in der Form „Used 14 times, last 3 Jul". Dies ist die schnellste Möglichkeit, um zu bestätigen, dass Ihr CMS den Hook tatsächlich aufruft, wenn Sie es erwarten.
Wenn die Anzahl nicht ansteigt, liegt das Problem auf der Aufruferseite: Überprüfen Sie, ob die Methode POST ist, die URL genau ist und die Integration nicht stumm bei einem TLS- oder Firewall-Fehler fehlschlägt.
Einen Hook löschen
Klicken Sie in der Zeile auf Delete hook und bestätigen Sie. Der Dialog warnt, dass jeder Service, der ihn verwendet, nicht mehr funktioniert, was genau das ist, was passiert.
Es gibt keine Möglichkeit, das Token eines Hooks an Ort und Stelle zu rotieren. Wenn eine URL durchsickert, löschen Sie den Hook und erstellen Sie einen neuen, aktualisieren Sie dann jedes System, das die alte URL verwendet hat. Das Löschen wird sofort wirksam, also planen Sie den Swap, bevor Sie löschen, nicht danach.
Fehlerbehebung
Nichts passiert, wenn ich den Hook aufrufe. Überprüfen Sie, ob die Methode POST ist. Überprüfen Sie die URL Zeichen für Zeichen, einschließlich des Tokens. Überprüfen Sie die Nutzungsanzahl des Hooks auf der Registerkarte Hooks: Wenn sie nicht ansteigt, kam die Anfrage nie an.
Der Hook gibt einen Fehler zum neuesten Commit zurück. Orbit konnte den Branch-Head von Ihrem Git-Provider nicht lesen. Verbinden Sie den Provider erneut von Orbit, dann New project, dann Reconnect, und bestätigen Sie, dass das Repository noch zugänglich ist.
Der Hook gibt einen Fehler zur Zielumgebung zurück. Die Umgebung, auf die der Hook verwiesen hat, existiert nicht mehr, höchstwahrscheinlich weil eine Staging-Umgebung gelöscht wurde. Löschen Sie den Hook und erstellen Sie einen neuen gegen eine aktive Umgebung.
Der Hook wird ausgelöst, aber die Bereitstellung ist die gleiche wie das letzte Mal. Das ist das Deduplizierungsverhalten: Der Branch-Head hat sich nicht geändert, daher gibt es nichts Neues zum Aufbauen. Pushen Sie einen Commit, oder verwenden Sie Deploy now, wenn Sie speziell den gleichen Commit neu aufbauen möchten.
Weiterführende Lektüre
- Deploying Your Project für die Deploy-Gates und welche davon Hooks umgehen
- Connecting a Bitbucket Repo für den CI-Gating-Fall, den Hooks lösen
- Environment Variables, da ein Hook-ausgelöster Build die gleiche Konfiguration wie jeder andere liest