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…

Déclencher des déploiements via les Deploy Hooks

Un deploy hook est une URL secrète qui met en file d'attente un nouveau déploiement quand quelque chose lui envoie une requête HTTP POST. Il n'y a pas d'en-tête d'authentification : le secret de l'URL est l'authentification. Utilisez les hooks pour permettre à un CMS headless, une tâche cron, un pipeline CI ou tout autre webhook de reconstruire votre projet sans git push.

Où trouver les Deploy Hooks

Les hooks ont leur propre onglet : ouvrez votre projet dans Orbit et cliquez sur Hooks, à /orbit/<project-id>/hooks.

Le même panneau Deploy hooks apparaît également à mi-chemin de l'onglet Settings du projet, vous pouvez donc les gérer à partir de l'un ou l'autre endroit.

Deploy hooks panel in Orbit

Créer un Deploy Hook

Ouvrez Orbit, puis votre projet, puis Hooks.
Cliquez sur Add deploy hook.
Entrez un Hook name qui aura encore du sens dans six mois. L'exemple sugère la forme : « Contentful publish », « Nightly cron ».
Choisissez un Target environment. Il est défini par défaut sur Production (default). Si votre projet a un environnement de staging, vous pouvez pointer le hook vers staging à la place.
Cliquez sur Create hook.

Le hook apparaît dans la liste avec son URL, un bouton Copy URL et un bouton Delete hook.

L'URL du Hook

Les URLs de hooks ressemblent à ceci :

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

Le token est un secret unique généré quand vous créez le hook.

Traitez une URL de hook exactement comme une clé API. N'importe qui qui la possède peut déclencher un déploiement de votre projet, et aucune des portes de déploiement d'Orbit ne l'arrêtera : les verrous de déploiement, l'approbation requise, les vérifications CI requises et le succès de staging requis s'appliquent uniquement aux déploiements déclenchés par push, et un hook passe directement. Ne collez jamais une URL de hook dans un référentiel public, un document partagé, une capture d'écran ou un ticket de support.

Déclencher un Hook

Envoyez une requête POST. Aucun corps et aucun en-têtes ne sont requis.

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

Orbit répond avec HTTP 202 et l'ID de déploiement. Le déploiement apparaît sur l'onglet Deployments en quelques secondes.

Le point de terminaison accepte POST uniquement. Une requête GET ne déclenchera pas de déploiement. Certaines intégrations webhook plus anciennes utilisent GET par défaut, vérifiez donc la méthode si un hook que vous avez configuré ne se déclenche jamais.

Ce qu'un Hook Déploie Réellement

Le hook résout son environnement cible (celui que vous avez choisi, ou l'environnement de production du projet), lit la branche de cet environnement, et demande à votre fournisseur git le commit head actuel de cette branche. Il met ensuite en file d'attente un déploiement de ce commit.

Cela a trois conséquences à connaître :

Un hook déploie toujours le branch head. Vous ne pouvez pas passer un SHA de commit ou un nom de branche dans le corps de la requête ; le corps de la requête est entièrement ignoré.
Un hook a besoin d'une connexion fournisseur fonctionnelle. Si vous avez déconnecté GitHub, GitLab ou Bitbucket, le hook ne peut pas lire le branch head et échoue avec une erreur plutôt que de déployer du code obsolète.
Un hook relance la construction complète. Ce n'est pas un rollback et pas une promotion ; c'est une construction fraîche de ce qui se trouve actuellement sur la branche.

Appels Répétés et Chevauchants

Orbit gère les rafales d'appels de hook intelligemment plutôt que de mettre en file d'attente une construction pour chacun.

Si un déploiement du même commit est déjà en vol sur cet environnement, le hook retourne le déploiement existant et marque la réponse comme dédupliquée. Aucune seconde construction ne démarre.
Si une construction s'exécute pour un commit différent sur cet environnement, elle est automatiquement annulée et remplacée par la nouvelle, vous ne payez donc pas pour une construction dont la sortie est déjà dépréciée.

Cela rend les hooks sûrs pour un CMS qui déclenche un webhook par entrée publiée. Publier six pages en une minute produit une construction, pas six, et ne consomme pas six constructions' worth de minutes.

Connecter un CMS Headless

La plupart des CMS headless ont une fonctionnalité « webhook on publish ». Le pattern est toujours le même : pointez le webhook vers votre URL de hook, utilisez POST, et laissez les paramètres d'authentification vides.

Contentful

Allez à Settings, puis Webhooks, puis Add webhook.
Définissez l'URL sur votre URL de hook Orbit.
Définissez la méthode sur POST.
Définissez le déclencheur sur Publish, ou sur les événements de contenu qui devraient reconstruire le site.
Enregistrez.

Sanity

Dans votre tableau de bord de projet, allez à API, puis Webhooks, puis Create webhook. Définissez l'URL sur votre URL de hook, la méthode sur POST, et choisissez le dataset et les événements déclencheurs.

Prismic

Dans le tableau de bord, allez à Settings, puis Webhooks, et ajoutez votre URL de hook. Prismic l'appelle à chaque publication de document.

Connecter une Tâche Cron ou un Pipeline CI

N'importe quel planificateur capable de faire une requête HTTP fera l'affaire :

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

Pour CI, un deploy hook est l'option la plus simple quand vous voulez que votre pipeline décide si un déploiement se produit. C'est l'approche recommandée pour Bitbucket Pipelines, car le paramètre CI required checks d'Orbit s'applique aux noms de tâches GitHub Actions ou à un pipeline GitLab, pas à Bitbucket.

Si vous avez besoin de plus que « déployer le branch head », utilisez un API token à la place d'un hook. Orbit, puis Tokens, crée des jetons bearer délimités pour CI/CD avec une API REST documentée et un workflow GitHub Actions prêt à l'emploi. L'accès à l'API est inclus dans le plan Apex.

Reconstruire selon un horaire Sans un Hook

Si tout ce que vous voulez est une reconstruction périodique, vous n'avez pas besoin d'un hook du tout. Scheduled rebuild dans Settings, sous Runtime, reconstruit la production automatiquement toutes les heures, 6 heures, 12 heures, quotidiennement, tous les 2 jours ou hebdomadairement. C'est construit pour exactement le cas du site piloté par CMS et il n'y a pas d'URL secrète à protéger.

Vérifier l'Activité du Hook

Chaque ligne de hook montre combien de fois elle a été utilisée et quand elle a été utilisée pour la dernière fois, sous la forme « Used 14 times, last 3 Jul ». C'est le moyen le plus rapide de confirmer que votre CMS appelle réellement le hook quand vous pensez qu'il le fait.

Si le compte ne monte pas, le problème vient du côté appelant : vérifiez que la méthode est POST, l'URL est exacte, et l'intégration ne échoue pas silencieusement sur une erreur TLS ou pare-feu.

Supprimer un Hook

Cliquez sur Delete hook sur la ligne et confirmez. La boîte de dialogue avertit que tout service l'utilisant cessera de fonctionner, ce qui est exactement ce qui se passe.

Il n'y a aucun moyen de faire pivoter le token d'un hook en place. Si une URL fuit, vous supprimez le hook et en créez un nouveau, puis mettez à jour chaque système qui a utilisé l'ancienne URL. La suppression prend effet immédiatement, planifiez donc l'échange avant de supprimer plutôt qu'après.

Dépannage

Rien ne se passe quand j'appelle le hook. Vérifiez que la méthode est POST. Vérifiez l'URL caractère par caractère, y compris le token. Vérifiez le compte d'utilisation du hook sur l'onglet Hooks : s'il n'augmente pas, la requête n'est jamais arrivée.

Le hook retourne une erreur au sujet du dernier commit. Orbit n'a pas pu lire le branch head de votre fournisseur git. Reconnectez le fournisseur depuis Orbit, puis New project, puis Reconnect, et confirmez que le référentiel est toujours accessible.

Le hook retourne une erreur au sujet de l'environnement cible. L'environnement vers lequel le hook pointait n'existe plus, très probablement parce qu'un environnement de staging a été supprimé. Supprimez le hook et créez-en un nouveau pour un environnement actif.

Le hook se déclenche mais le déploiement est le même qu'avant. C'est le comportement de déduplication : le branch head n'a pas changé, il n'y a donc rien de nouveau à construire. Poussez un commit, ou utilisez Deploy now si vous voulez spécifiquement reconstruire le même commit.

Lectures Connexes

Deploying Your Project pour les portes de déploiement et lesquelles d'entre elles les hooks contournent
Connecting a Bitbucket Repo pour le cas de gating CI que les hooks résolvent
Environment Variables, car une construction déclenchée par hook lit la même configuration que n'importe quelle autre

Déclencher des déploiements via des webhooks de déploiement