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…

Implementaties activeren via Deploy Hooks

Een deploy hook is een geheime URL die een nieuwe implementatie in de wachtrij plaatst wanneer iets er een HTTP POST naar stuurt. Er is geen authenticatieheader: het geheim van de URL is de authenticatie. Gebruik hooks zodat een headless CMS, een cronjob, een CI-pipeline of een ander webhook uw project kan herbouwen zonder een git push.

Deploy Hooks vinden

Hooks hebben hun eigen tabblad: open uw project in Orbit en klik op Hooks, op /orbit/<project-id>/hooks.

Hetzelfde Deploy hooks paneel verschijnt ook halverwege het tabblad Settings van het project, zodat u ze van beide plekken kunt beheren.

Deploy hooks paneel in Orbit

Een Deploy Hook maken

Open Orbit, vervolgens uw project, vervolgens Hooks.
Klik op Add deploy hook.
Voer een Hook name in die nog steeds logisch is over zes maanden. De placeholder suggereert de vorm: "Contentful publish", "Nightly cron".
Kies een Target environment. Het is standaard ingesteld op Production (default). Als uw project een stagingomgeving heeft, kunt u de hook in plaats daarvan naar staging wijzen.
Klik op Create hook.

De hook verschijnt in de lijst met zijn URL, een Copy URL knop en een Delete hook knop.

De Hook URL

Hook URL's zien er als volgt uit:

https://kpanel.kapsulehost.com/api/orbit/hooks/<token>

Het token is een unieke geheime sleutel die wordt gegenereerd wanneer u de hook maakt.

Behandel een hook URL precies als een API-sleutel. Iedereen die deze heeft, kan een implementatie van uw project activeren, en geen van Orbit's implementatiepoorten zal hen tegenhouden: implementatievergrendelingen, vereiste goedkeuring, vereiste CI-controles en vereiste stagingsucces gelden allemaal alleen voor push-geactiveerde implementaties, en een hook gaat er rechtdoor. Plak een hook URL nooit in een openbare repository, een gedeeld document, een schermafbeelding of een supportticket.

Een Hook activeren

Stuur een POST-verzoek. Geen body en geen headers zijn vereist.

curl -X POST \
  https://kpanel.kapsulehost.com/api/orbit/hooks/<your-token>

Orbit antwoordt met HTTP 202 en de implementatie-ID. De implementatie verschijnt binnen enkele seconden op het tabblad Deployments.

Het eindpunt accepteert alleen POST. Een GET-verzoek zal een implementatie niet activeren. Sommige oudere webhookintegraties standaard op GET, dus controleer de methode als een hook die u hebt geconfigureerd nooit wordt geactiveerd.

Wat een Hook daadwerkelijk implementeert

De hook lost de doelomgeving op (degene die u hebt gekozen, of de productieomgeving van het project), leest de branch van die omgeving, en vraagt uw gitprovider naar de huidige head commit van die branch. Vervolgens plaatst het een implementatie van die commit in de wachtrij.

Dit heeft drie gevolgen die het waard zijn om te weten:

Een hook implementeert altijd de branch head. U kunt geen commit SHA of branchnaam in de request body doorgeven; de request body wordt volledig genegeerd.
Een hook heeft een werkende providerverbinding nodig. Als u GitHub, GitLab of Bitbucket hebt verbroken, kan de hook de branch head niet lezen en mislukt deze met een fout in plaats van verouderde code te implementeren.
Een hook voert de volledige build opnieuw uit. Het is geen terugdraaiing en geen promotie; het is een frisse build van wat momenteel op de branch staat.

Herhaalde en overlappende oproepen

Orbit behandelt pieken van hook-aanroepen op een verstandige manier in plaats van voor elk één build in de wachtrij te plaatsen.

Als een implementatie voor dezelfde commit al actief is in die omgeving, retourneert de hook de bestaande implementatie en markeert het antwoord als gededupliceerd. Geen tweede build begint.
Als een build wordt uitgevoerd voor een andere commit in die omgeving, wordt deze automatisch geannuleerd en vervangen door de nieuwe, zodat u niet betaalt voor een build waarvan de uitvoer al verouderd is.

Dit maakt hooks veilig voor een CMS die per gepubliceerde entry een webhook afvuurt. Het publiceren van zes pagina's in een minuut resulteert in één build, niet zes, en verbruikt niet zes builds' minuten.

Een Headless CMS verbinden

De meeste headless CMSen hebben een "webhook on publish" functie. Het patroon is altijd hetzelfde: wijs de webhook naar uw hook URL, gebruik POST, en laat de verificatie-instellingen leeg.

Contentful

Ga naar Settings, vervolgens Webhooks, vervolgens Add webhook.
Stel de URL in op uw Orbit hook URL.
Stel de methode in op POST.
Stel de trigger in op Publish, of welke content-events ook de site moeten herbouwen.
Opslaan.

Sanity

Ga in uw projectdashboard naar API, vervolgens Webhooks, vervolgens Create webhook. Stel de URL in op uw hook URL, de methode op POST, en kies de dataset en triggergebeurtenissen.

Prismic

Ga in het dashboard naar Settings, vervolgens Webhooks, en voeg uw hook URL toe. Prismic roept het op voor elke documentpublicatie.

Een Cronjob of CI-pipeline verbinden

Elke scheduler die een HTTP-verzoek kan doen, werkt:

# crontab: rebuild every night at 2am
0 2 * * * curl -fsS -X POST https://kpanel.kapsulehost.com/api/orbit/hooks/<your-token>

Voor CI is een deploy hook de eenvoudigste optie wanneer u wilt dat uw pipeline beslist of een implementatie gebeurt. Dit is de aanbevolen aanpak voor Bitbucket Pipelines, omdat Orbit's CI vereiste controles-instelling op GitHub Actions jobnamen of GitLab-pipeline werkt, niet op Bitbucket.

Als u meer dan "implementeer de branch head" nodig hebt, gebruik dan in plaats daarvan een API-token. Orbit, vervolgens Tokens, maakt scoped bearer tokens voor CI/CD met een gedocumenteerde REST API en een kant-en-klare GitHub Actions workflow. API-toegang is inbegrepen in het Apex-plan.

Herbouwen op schema zonder een Hook

Als u alleen een periodieke herbouw wilt, hebt u helemaal geen hook nodig. Scheduled rebuild in Settings, onder Runtime, herbouwt production automatisch elk uur, 6 uur, 12 uur, dagelijks, elke 2 dagen of wekelijks. Dit is gemaakt voor precies het CMS-gestuurde-site geval en er is geen geheime URL om te beschermen.

Hook-activiteit controleren

Elke hook-rij toont hoe vaak deze is gebruikt en wanneer deze voor het laatst is gebruikt, in de vorm "Used 14 times, last 3 Jul". Dit is de snelste manier om te bevestigen dat uw CMS daadwerkelijk de hook aanroept wanneer u dat verwacht.

Als het getal niet omhoog gaat, is het probleem aan de bellers-zijde: controleer of de methode POST is, de URL exact is, en de integratie niet stil mislukt op een TLS- of firewallfout.

Een Hook verwijderen

Klik op Delete hook op de rij en bevestig. Het dialoogvenster waarschuwt dat elke service die het gebruikt zal stoppen met werken, wat precies gebeurt.

Er is geen manier om het token van een hook ter plaatse te roteren. Als een URL lekt, verwijdert u de hook en maakt u een nieuwe, en werkt u vervolgens elk systeem bij dat de oude URL gebruikte. Verwijdering wordt onmiddellijk van kracht, dus plan de wissel voordat u verwijdert in plaats van daarna.

Probleemoplossing

Niets gebeurt wanneer ik de hook aanroep. Controleer of de methode POST is. Controleer de URL karakter voor karakter, inclusief het token. Controleer het gebruiksaantal van de hook op het tabblad Hooks: als dit niet toeneemt, is het verzoek nooit aangekomen.

De hook retourneert een fout over de laatste commit. Orbit kon de branch head niet van uw gitprovider lezen. Verbind de provider opnieuw vanuit Orbit, vervolgens New project, vervolgens Reconnect, en bevestig dat de repository nog steeds toegankelijk is.

De hook retourneert een fout over de doelomgeving. De omgeving waar de hook naar wees, bestaat niet meer, waarschijnlijk omdat een stagingomgeving is verwijderd. Verwijder de hook en maak een nieuwe tegen een live omgeving.

De hook wordt afgevuurd, maar de implementatie is hetzelfde als de vorige keer. Dat is het deduplicatiegedrag: de branch head is niet veranderd, dus er is niets nieuws om te bouwen. Push een commit, of gebruik Deploy now als u specifiek dezelfde commit opnieuw wilt bouwen.

Gerelateerde onderwerpen

Deploying Your Project voor de implementatiepoorten en welke ervan hooks omzeilen
Connecting a Bitbucket Repo voor het CI-gatingcasus dat hooks oplossen
Environment Variables, aangezien een door hook geactiveerde build dezelfde configuratie leest als elke andere

Deploy Hooks via implementeren activeren