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…

Attivare i deploy tramite Deploy Hooks

Un deploy hook è un URL segreto che mette in coda un nuovo deployment quando riceve una richiesta HTTP POST. Non c'è alcun header di autenticazione: la segretezza dell'URL è l'autenticazione. Usa gli hook per consentire a un CMS headless, un job cron, una pipeline CI o qualsiasi altro webhook di ricostruire il tuo progetto senza un git push.

Dove trovare i Deploy Hooks

Gli hook hanno una scheda dedicata: apri il tuo progetto in Orbit e fai clic su Hooks, in /orbit/<project-id>/hooks.

Lo stesso pannello Deploy hooks appare anche a metà della scheda Settings del progetto, quindi puoi gestirli da entrambi i luoghi.

Deploy hooks panel in Orbit

Creare un Deploy Hook

Apri Orbit, poi il tuo progetto, poi Hooks.
Fai clic su Add deploy hook.
Inserisci un Hook name che avrà ancora senso tra sei mesi. Il placeholder suggerisce il formato: "Contentful publish", "Nightly cron".
Scegli un Target environment. Di default è Production (default). Se il tuo progetto ha un ambiente di staging, puoi indirizzare l'hook a staging.
Fai clic su Create hook.

L'hook appare nell'elenco con il suo URL, un pulsante Copy URL e un pulsante Delete hook.

L'URL dell'Hook

Gli URL degli hook assomigliano a questo:

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

Il token è un segreto univoco generato quando crei l'hook.

Tratta un URL hook esattamente come una chiave API. Chiunque lo possieda può attivare un deployment del tuo progetto, e nessuno dei gate di deploy di Orbit li fermerà: i deploy lock, l'approvazione richiesta, i controlli CI richiesti e il successo dello staging richiesto si applicano solo ai deploy attivati da push, e un hook passa direttamente. Non incollare mai un URL hook in un repository pubblico, un documento condiviso, uno screenshot o un ticket di supporto.

Attivare un Hook

Invia una richiesta POST. Non sono richiesti corpo e header.

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

Orbit risponde con HTTP 202 e l'ID del deployment. Il deployment appare sulla scheda Deployments entro pochi secondi.

L'endpoint accetta solo POST. Una richiesta GET non attiverà un deployment. Alcune integrazioni webhook più vecchie di default usano GET, quindi controlla il metodo se un hook che hai configurato non si attiva mai.

Cosa effettivamente distribuisce un Hook

L'hook risolve il suo ambiente target (quello che hai scelto, o l'ambiente di produzione del progetto), legge il branch di quell'ambiente, e chiede al tuo provider git il commit head corrente di quel branch. Poi mette in coda un deployment di quel commit.

Questo ha tre conseguenze che vale la pena conoscere:

Un hook distribuisce sempre il branch head. Non puoi passare un SHA di commit o un nome di branch nel corpo della richiesta; il corpo della richiesta è completamente ignorato.
Un hook ha bisogno di una connessione provider funzionante. Se hai disconnesso GitHub, GitLab o Bitbucket, l'hook non può leggere il branch head e fallisce con un errore piuttosto che distribuire codice obsoleto.
Un hook riesegue la build completa. Non è un rollback e non è una promozione; è una build fresca di qualsiasi cosa sia attualmente nel branch.

Chiamate Ripetute e Sovrapposte

Orbit gestisce raffiche di chiamate hook in modo sensato piuttosto che mettere in coda una build per ognuna.

Se un deployment per lo stesso commit è già in corso su quell'ambiente, l'hook restituisce il deployment esistente e marca la risposta come deduplicata. Non inizia una seconda build.
Se una build è in esecuzione per un commit diverso su quell'ambiente, viene automaticamente annullata e sostituita da quella nuova, quindi non paghi per una build il cui output è già superato.

Questo rende gli hook sicuri per un CMS che attiva un webhook per voce pubblicata. Pubblicare sei pagine in un minuto produce una build, non sei, e non consuma sei build di minuti.

Connettere un CMS Headless

La maggior parte dei CMS headless ha una funzione "webhook on publish". Il pattern è sempre lo stesso: indirizza il webhook al tuo URL hook, usa POST e lascia vuote le impostazioni di autenticazione.

Contentful

Vai a Settings, poi Webhooks, poi Add webhook.
Imposta l'URL al tuo URL hook di Orbit.
Imposta il metodo a POST.
Imposta il trigger a Publish, o qualsiasi evento di contenuto dovrebbe ricostruire il sito.
Salva.

Sanity

Nel dashboard del tuo progetto, vai a API, poi Webhooks, poi Create webhook. Imposta l'URL al tuo URL hook, il metodo a POST, e scegli il dataset e gli eventi trigger.

Prismic

Nel dashboard, vai a Settings, poi Webhooks, e aggiungi il tuo URL hook. Prismic lo chiama ad ogni pubblicazione di documento.

Connettere un Job Cron o una Pipeline CI

Qualsiasi scheduler che possa fare una richiesta HTTP funzionerà:

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

Per CI, un deploy hook è l'opzione più semplice quando vuoi che la tua pipeline decida se deve avvenire un deploy. È l'approccio consigliato per Bitbucket Pipelines, poiché l'impostazione CI required checks di Orbit si basa sui nomi dei job di GitHub Actions o su una pipeline GitLab, non su Bitbucket.

Se hai bisogno di più di "distribuisci il branch head", usa un token API invece di un hook. Orbit, poi Tokens, crea token bearer con scope per CI/CD con un'API REST documentata e un workflow GitHub Actions pronto all'uso. L'accesso API è incluso nel piano Apex.

Ricostruire secondo una pianificazione senza un Hook

Se tutto quello che vuoi è una ricostruzione periodica, non hai affatto bisogno di un hook. Scheduled rebuild in Settings, sotto Runtime, ricostruisce la produzione automaticamente ogni ora, 6 ore, 12 ore, giornalmente, ogni 2 giorni o settimanalmente. È costruito esattamente per il caso di sito guidato dal CMS e non c'è alcun URL segreto da proteggere.

Verificare l'Attività dell'Hook

Ogni riga dell'hook mostra quante volte è stata utilizzata e quando è stata utilizzata l'ultima volta, nel formato "Used 14 times, last 3 Jul". Questo è il modo più veloce per confermare che il tuo CMS sta effettivamente chiamando l'hook quando pensi che lo faccia.

Se il conteggio non aumenta, il problema è dal lato chiamante: controlla che il metodo sia POST, l'URL sia esatto, e l'integrazione non stia fallendo silenziosamente su un errore TLS o firewall.

Eliminare un Hook

Fai clic su Delete hook sulla riga e conferma. La finestra di dialogo avverte che qualsiasi servizio che lo utilizza smetterà di funzionare, il che è esattamente quello che accade.

Non c'è modo di ruotare il token di un hook sul posto. Se un URL trapela, elimini l'hook e ne crei uno nuovo, poi aggiorni ogni sistema che ha usato l'URL precedente. L'eliminazione ha effetto immediato, quindi pianifica lo scambio prima di eliminare piuttosto che dopo.

Risoluzione dei Problemi

Nulla accade quando chiamo l'hook. Controlla che il metodo sia POST. Controlla l'URL carattere per carattere, incluso il token. Controlla il conteggio di utilizzo dell'hook sulla scheda Hooks: se non sta aumentando, la richiesta non è mai arrivata.

L'hook restituisce un errore sul commit più recente. Orbit non ha potuto leggere il branch head dal tuo provider git. Ricollega il provider da Orbit, poi New project, poi Reconnect, e conferma che il repository sia ancora accessibile.

L'hook restituisce un errore sull'ambiente target. L'ambiente a cui l'hook puntava non esiste più, molto probabilmente perché un ambiente di staging è stato eliminato. Elimina l'hook e creane uno nuovo per un ambiente attivo.

L'hook si attiva ma il deploy è lo stesso di prima. Questo è il comportamento di deduplicazione: il branch head non è cambiato, quindi non c'è nulla di nuovo da costruire. Esegui un push di un commit, o usa Deploy now se vuoi specificamente ricostruire lo stesso commit.

Letture Correlate

Deploying Your Project per i deploy gate e quali di essi gli hook bypassano
Connecting a Bitbucket Repo per il caso di gating CI che gli hook risolvono
Environment Variables, poiché una build attivata da hook legge la stessa configurazione di qualsiasi altra

Attivazione di Implementazioni Tramite Deploy Hooks