Webhooks et automatisations
Webhooks et automatisations
Faire en sorte que DeployIt reçoive les événements push, pull request et release — création automatique, secrets et résolution des erreurs.
Créez, vérifiez et maintenez les webhooks nécessaires pour que vos repositories déclenchent les automatisations DeployIt.
Ce que couvre cette page
Création automatique
Créer un webhook directement depuis la vue repository : DeployIt propose un bouton “Create webhook” qui crée le hook côté fournisseur et génère un secret si nécessaire.
Événements supportés
Push, Pull Request (merge/merge_request) et Release — DeployIt écoute ces événements pour déclencher agents et hooks.
Sécurité et secrets
Generation et stockage d’un secret signé par DeployIt ; possibilité de régénérer/mettre à jour le secret depuis l’interface.
Diagnostic & vérification
Vérifiez l’existence du webhook, inspectez les livraisons des événements et testez la configuration côté fournisseur.
Gestion des permissions
Guides pratiques pour résoudre les échecs liés aux permissions (tokens expirés, droits manquants, installations d’app).
Fallback manuel
Si la création automatique échoue, procédure pas-à-pas pour créer et lier un webhook manuellement.
Introduction Ce guide explique, pas à pas, comment créer, vérifier et maintenir les webhooks qui permettent à DeployIt de recevoir les événements de vos repositories (push, pull request/merge request, release). Il décrit la création automatique depuis la vue repository, la génération et la rotation des secrets, les différences GitHub / GitLab, et comment résoudre les erreurs liées aux permissions ou aux tokens.
Avant de commencer
Si vous êtes dans une organisation, vérifiez avec l’administrateur que l’application DeployIt (ou vos tokens OAuth personnels) dispose des droits d’administration sur le repository. Sans ces droits la création automatique échouera.
Créer automatiquement un webhook depuis la vue repository
Étape 1 — Ouvrir la vue Repository
Dans le tableau de bord du projet, ouvrez l’onglet Repositories et sélectionnez le repository concerné.
Étape 2 — Lancer la création
Cliquez sur le bouton “Create webhook” (ou équivalent) visible dans la fiche du repository. Ce bouton déclenche la création côté fournisseur par DeployIt.
Étape 3 — Confirmation & génération de secret
Si le repository n’a pas de secret webhook, DeployIt génère automatiquement un secret et l’associe au repository dans l’interface. Vous verrez un message de succès ou un message d’erreur détaillant la raison du refus.
Étape 4 — Que faire en cas de succès
- Vérifiez que l’état affiché pour le webhook indique “créé” ou “actif”.
- Optionnel : consultez les journaux de livraisons côté fournisseur pour confirmer des réponses 2xx lorsque des événements arrivent.
Étape 5 — En cas d’échec initial
Si la création échoue, notez le message d’erreur et suivez la section “Résolution des erreurs courantes” plus bas. Les causes fréquentes : permissions insuffisantes, token expiré, installation d’app non autorisée.
Affichage clair des erreurs
Lorsque la création échoue, l’interface affiche généralement une raison exploitable (ex : permission manquante). Copiez ce message avant de relancer une tentative ou de demander de l’aide.
DeployIt crée le webhook en demandant les événements push et pull_request. Deux cas fréquents :
- Si vous utilisez un token OAuth personnel, le token doit permettre la gestion des webhooks (droits admin pour le repo ou admin:repo_hook).
- Si votre organisation utilise une application GitHub (GitHub App), DeployIt peut utiliser le jeton lié à l’installation — dans ce cas l’application doit être installée sur le repository/organisation.
Avant (création manuelle fréquente)
- Nécessité de connaître l’URL de callback.
- Copier/coller du secret entre la plateforme et DeployIt.
- Risque d’erreurs de configuration (types d’événements, content-type).
Après (création automatique)
- Un clic depuis la vue repository lance la création.
- DeployIt génère et stocke le secret le cas échéant.
- Moins d’erreurs manuelles et gain de temps.
Limite importante — permissions requises
La création automatique d’un webhook peut échouer si l’utilisateur ou l’application ne dispose pas des droits d’administration sur le repository. Pour GitHub, cela correspond souvent à l’autorisation de gérer les hooks ; pour GitLab, au rôle Maintainer. Si vous obtenez une erreur liée aux permissions, demandez une réauthentification ou l’intervention d’un administrateur.
Vérifier qu’un webhook existe et fonctionne
Étape 1 — Vérification rapide sur DeployIt
Dans la fiche du repository, cherchez l’indicateur d’état du webhook (ex. “Webhook actif” / “Hook présent”). DeployIt affiche si un secret est connu et si un hook a été créé.
Étape 2 — Vérifier côté fournisseur
Sur GitHub : Repository > Settings > Webhooks.
Sur GitLab : Project > Settings > Webhooks.
Repérez le webhook DeployIt (URL de réception) et vérifiez qu’il est actif.
Étape 3 — Inspecter les livraisons
Consultez l’historique des livraisons (deliveries) côté fournisseur : recherchez les entrées récentes, l’état HTTP retourné (200/2xx attendu) et les éventuelles erreurs 4xx/5xx.
Étape 4 — Tester manuellement
- Pour GitHub : utilisez la fonction “Redeliver” ou “Test delivery”.
- Pour GitLab : utilisez “Trigger” ou envoyez un push test sur une branche.
Vérifiez que DeployIt reçoit l’événement et déclenche l’automatisation attendue.
Étape 5 — Valider le secret
Si la livraison échoue avec 401/403, vérifiez que le secret configuré chez le fournisseur correspond exactement au secret stocké dans DeployIt. Si nécessaire, régénérez et synchronisez-les.
Tester dans un environnement contrôlé
Avant d’activer un webhook sur un repo critique, créez une branche ou un repo de test. Envoyez quelques pushes et PR simulées pour vérifier les automatisations sans impacter la production.
Créer un webhook manuellement (si la création automatique échoue)
Étape 1 — Obtenir l’URL de réception DeployIt
Dans la section webhooks ou les paramètres du projet DeployIt, copiez l’URL de réception fournie (elle contiendra la route webhook dédiée à DeployIt).
Étape 2 — Créer le webhook sur le fournisseur
- GitHub : Repository > Settings > Webhooks > Add webhook.
- Payload URL : coller l’URL DeployIt.
- Content type : application/json.
- Secret : choisissez un token sécurisé (DeployIt peut en générer un si vous le collez ensuite).
- Events : Push et Pull Request (et Release si besoin).
- GitLab : Project > Settings > Webhooks.
- URL : coller l’URL DeployIt.
- Select Push events, Merge requests events, Tag push (release) si utile.
- Secret token : idem.
Étape 3 — Enregistrer et tester
Sauvegardez la configuration et utilisez la fonction de test fournie (ou réalisez un push test). Vérifiez les livraisons côté provider et que DeployIt réagit.
Étape 4 — Synchroniser le secret avec DeployIt
Si vous avez choisi le secret côté fournisseur, collez-le dans le champ secret du repository dans DeployIt pour que les signatures soient validées.
Étape 5 — Documenter
Notez où le secret est stocké et qui a le droit de le régénérer. Conservez la traçabilité des actions réalisées.
Régénérer ou faire pivoter un secret webhook
Étape 1 — Planifier la rotation
Annoncer la fenêtre de maintenance, car la rotation temporairement interrompra la validation des livraisons si la synchronisation est tardive.
Étape 2 — Générer un nouveau secret dans DeployIt
Dans la fiche du repository, utilisez l’action “Regenerate secret” ou notez la valeur fournie par DeployIt.
Étape 3 — Mettre à jour côté fournisseur
Collez le nouveau secret dans la configuration du webhook chez GitHub/GitLab et sauvegardez.
Étape 4 — Tester immédiatement
Effectuez un test de livraison ou un push test. Confirmez que les livraisons retournent 2xx et que DeployIt traite l’événement.
Étape 5 — Revoquer l’ancien secret
Si le fournisseur permet de conserver l’historique, supprimez/replacez l’ancien secret pour éviter tout risque d’exposition.
Résolution des erreurs courantes et actions recommandées
Erreur : ‘permission denied’ ou échec list webhooks
Cause probable : le token utilisé n’a pas les droits d’administration sur le repository. Actions :
- Demandez à l’admin du repo de fournir un token avec droits de gestion des webhooks ou d’installer l’application DeployIt sur l’organisation/repo.
- Si vous utilisez un token personnel, ré-authentifiez-vous et assurez-vous d’accorder les scopes requis.
Erreur : ‘No access token available’ (DeployIt indique l’absence de token)
Cause probable : le repository n’est pas ré-authentifié ou vous avez connecté le repo sans token valide. Actions : ré-authentifiez le provider depuis la page de connexions Git de votre projet.
Erreur : Webhook déjà existant
Si DeployIt détecte un webhook existant, il ne créera pas un doublon. Vérifiez la configuration existante chez le fournisseur et assurez-vous que le secret est synchronisé avec DeployIt.
Erreur : livraisons retournent 4xx/5xx
- 401/403 : problème d’authentification ou secret invalide. Comparez le secret.
- 404 : l’URL de réception n’est pas accessible depuis l’extérieur (pare-feu, URL interne). Assurez-vous que DeployIt est accessible publiquement si nécessaire.
- 5xx : problème temporaire côté DeployIt ou surcharge ; réessayez et consultez les journaux.
Erreur : création bloquée par politique d’organisation / SAML / SSO
Certaines organisations exigent l’approbation d’applications ou imposent des restrictions SSO. Actions : demander à l’administrateur organisationnel d’autoriser explicitement DeployIt ou d’installer l’application pour l’organisation.
Quand demander de l’aide à l’administrateur
Si vous ne pouvez pas obtenir les droits nécessaires ou si le repository appartient à une organisation, sollicitez un administrateur pour : installer l’app, fournir un token avec scope adéquat, ou réaliser la création manuelle du webhook.
Meilleure pratique sécurité
Restreignez qui peut régénérer le secret dans DeployIt et limitez l’accès aux pages de configuration des webhooks. Envisagez une rotation régulière (par ex. tous les 90 jours) et documentez chaque rotation.
Performance et fiabilité
Activez les événements minimum nécessaires (p. ex. supprimer comment ou issue events si non utilisés) pour réduire le volume de livraisons et éviter des exécutions inutiles des agents.
Frequently Asked Questions
Prêt à activer les webhooks pour vos repositories ?
Créez ou mettez à jour les webhooks depuis la fiche repository pour que vos automatisations DeployIt puissent commencer à traiter les événements.