Git Deploy connecte un repository à un site de sorte que chaque push vers la branche choisie clone le code, lance votre build et publie le résultat. Ce guide couvre la connexion initiale, les deux étapes côté repository qui finalisent la configuration, la lecture de l'historique des déploiements, et la détection de buildpack qui décide comment une application Node.js est construite.
Où se trouve Git Deploy
Ouvrez Sites web, cliquez sur le site, ouvrez le groupe Environment dans le menu de gauche du site, et choisissez Déploiement Git. Deux pages associées se trouvent à proximité :
- Déploiements, l'historique complet des déploiements pour ce site, dans le même groupe Environment.
- Buildpack, la stratégie de build détectée, sur les sites Node.js, dans le groupe Applications.
La page Git Deploy se décrit simplement elle-même : connectez un repository et chaque push vers votre branche configurée déclenche un build et un déploiement.
Connexion d'un repository
- Choisissez votre Provider : GitHub, GitLab ou Bitbucket.
- Saisissez l'URL du repository. Le format SSH est celui qu'il vous faut, par exemple
git@github.com:user/repo.git. - Définissez la Branch à partir de laquelle déployer. Le champ démarre à
main. - Définissez éventuellement une Commande de compilation, par exemple
npm run build. - Définissez éventuellement un Répertoire de sortie, par exemple
dist,public, ou.pour un repository déjà construit. - Cliquez sur Connecter le repository.
Laissez la commande de compilation et le répertoire de sortie vides si votre repository est déjà déployable tel quel, ce qui est le cas courant pour un site PHP classique ou statique.
Scripts avancés
En développant Avancé, deux champs supplémentaires apparaissent :
- Script de pré-déploiement, qui s'exécute avant le build.
- Script de post-déploiement, qui s'exécute après le déploiement.
Utilisez le hook de post-déploiement pour les actions qui doivent avoir lieu une fois le nouveau code en place : vider un cache applicatif, exécuter une migration de base de données, redémarrer un worker.
Déploiement automatique au push
Le bouton bascule en bas de la carte contrôle si les pushs déclenchent un déploiement ou non. Lorsqu'il est activé, chaque push vers la branche configurée déclenche un déploiement. Lorsqu'il est désactivé, les déploiements ne s'exécutent que lorsque vous les déclenchez manuellement avec Déployer maintenant.
Désactivez le déploiement automatique pendant un gel de code ou un incident plutôt que de déconnecter le repository. Déconnecter supprime la clé de déploiement et le secret du webhook, vous devrez donc refaire les deux étapes côté repository par la suite.
Finaliser la configuration dans votre repository
Connecter le repository dans KPanel n'est que la première des trois étapes. Tant qu'aucun déploiement n'a eu lieu, la page affiche une bannière indiquant Terminer la configuration : 2 étapes restantes avec tout ce dont vous avez besoin.
Étape 2 : ajouter la clé de déploiement
KapsuleHost a besoin d'un accès en lecture pour cloner votre repository. La bannière affiche une clé publique avec un bouton Copier la clé.
Collez-la dans les clés de déploiement de votre repository. Pour GitHub, la bannière propose un raccourci Ajouter à GitHub menant directement à la bonne page de paramètres. Un accès en lecture suffit ; n'accordez pas l'écriture.
Étape 3 : ajouter le webhook
Le webhook est ce qui indique à KapsuleHost qu'un push a eu lieu. La bannière vous fournit trois valeurs :
| Champ | Valeur |
|---|---|
| URL du payload | Une URL se terminant par /api/git-deploy/webhook/ suivie de l'ID de ce site |
| Secret | Un secret de signature généré, masqué jusqu'à ce que vous cliquiez sur l'icône en forme d'œil |
| Type de contenu | application/json |
Copiez chaque valeur dans les paramètres de webhook de votre repository. Pour GitHub, il existe un raccourci Ajouter un webhook à GitHub. Réglez le type de contenu sur JSON, et non sur le format-encodé par défaut, sinon le payload ne pourra pas être analysé.
Traitez le secret du webhook comme un mot de passe. Quiconque le possède, en plus de l'URL du payload, peut déclencher un déploiement de votre site. Les deux valeurs ne sont montrées qu'aux personnes pouvant déjà administrer le site, et le secret reste masqué derrière l'icône en forme d'œil tant que vous ne le demandez pas.
Déployer manuellement
Cliquez sur Déployer maintenant sur la page Git Deploy pour construire et déployer l'état actuel de la branche configurée sans pousser de commit. Cela fonctionne que le déploiement automatique soit activé ou non, ce qui en fait l'outil idéal pendant un gel : les pushs sont ignorés, mais vous pouvez tout de même livrer le correctif.
Lire l'historique des déploiements
Ouvrez Environment, puis Déploiements. La page s'intitule Historique des déploiements et liste chaque déploiement déclenché par webhook ou manuellement, du plus récent au plus ancien.
Chaque ligne comporte :
- Une icône de statut et le SHA court du commit, avec la branche sous forme de pastille.
- Le message de commit, ou Déploiement manuel s'il n'y avait aucun message de commit à afficher.
- L'auteur, depuis combien de temps cela s'est exécuté, combien de temps cela a pris, et ce qui l'a déclenché.
- Une pastille de statut.
Les statuts sont pending, building, deploying, success et failed. Tant que quelque chose est en cours, la page se rafraîchit automatiquement toutes les cinq secondes et affiche une note Rafraîchissement automatique sous le tableau, pour que vous puissiez la laisser ouverte et observer l'atterrissage d'un déploiement.
Quand un déploiement échoue
Une ligne en échec affiche un bouton Error à droite. Cliquez dessus pour développer la sortie d'erreur capturée directement en ligne, sans quitter la page. Cette sortie est le texte d'erreur propre au build, elle nomme donc généralement le fichier ou la commande qui a échoué.
Procédez dans cet ordre : lisez l'erreur, reproduisez la même commande de build en local, corrigez, poussez. Si le build fonctionne en local mais pas ici, la différence est presque toujours liée à l'environnement : une dépendance manquante installée globalement sur votre machine, ou un fichier présent dans votre répertoire de travail mais non commité.
Détection du buildpack
Sur les sites Node.js, la page Buildpack du groupe Applications montre comment KapsuleHost a décidé de construire votre application. La détection s'exécute sur les fichiers à la racine de votre repository, et la première correspondance l'emporte :
| Détecté | Déclencheur |
|---|---|
| Buildpack personnalisé | kapsule.config.yaml ou kapsule.config.yml à la racine |
| Buildpack Dockerfile | Dockerfile à la racine |
| Node.js | package.json avec un script start, build ou dev |
| Python | requirements.txt ou pyproject.toml |
| PHP | composer.json |
| Statique | index.html à la racine |
Si rien ne correspond, la page l'indique et liste les déclencheurs pris en charge. Ajoutez un Dockerfile ou un kapsule.config.yaml pour prendre explicitement le contrôle du build.
Lancer un build
Cliquez sur Lancer le build pour en mettre un en file d'attente. La page interroge le serveur toutes les trois secondes pendant qu'une exécution est en cours, et le tableau Builds récents affiche les dernières exécutions avec leur heure de début, leur type, leur statut, leur durée et la référence d'image résultante. Cliquez sur une ligne pour voir la fin de son journal.
Un seul build peut être en cours à la fois. Déclencher un second build pendant qu'un autre est en file d'attente ou en cours d'exécution est refusé avec le message Une construction est déjà en cours, ce qui est voulu : deux builds écrivant la même sortie en même temps, c'est ainsi qu'on obtient un site à moitié déployé.
Déconnexion
Cliquez sur Disconnect et confirmez. La confirmation est explicite sur l'ampleur de l'opération : la configuration de déploiement Git et la clé de déploiement sont supprimées, et les fichiers de votre site ne sont pas affectés. Le site continue de servir ce qui a été déployé en dernier.
Faites ensuite le ménage en supprimant la clé de déploiement et le webhook dans les paramètres de votre repository. Ils cesseront simplement de fonctionner, mais laisser des entrées mortes traîner complique le prochain audit.
Dépannage
Les pushs ne déclenchent rien. Vérifiez d'abord le bouton bascule de déploiement automatique, puis le webhook dans votre repository. La plupart des fournisseurs affichent les livraisons récentes et leurs codes de réponse, ce qui vous indique immédiatement si la requête a bien quitté votre repository.
Le clonage échoue. La clé de déploiement est manquante, a été collée avec un saut de ligne, ou a été ajoutée au mauvais repository. Copiez-la à nouveau avec le bouton Copier la clé plutôt que de sélectionner le texte à la main.
Le déploiement réussit mais le site ne change pas. Le répertoire de sortie est probablement incorrect. Si votre build écrit dans dist et que le répertoire de sortie est vide, les fichiers construits n'atteignent jamais la racine servie.
Tout indique pending et rien ne bouge. Le déploiement a été mis en file d'attente mais jamais pris en charge. Déclenchez un Déployer maintenant manuel et vérifiez la page Deploys à la recherche d'une ligne d'erreur.
Et ensuite ?
- Aperçus de déploiements pour les pull requests ajoute une URL par PR en plus de cette configuration.
- Stocker les secrets d'application pour un site pour les identifiants dont votre build et votre runtime ont besoin.
- Journal d'activité du site enregistre les modifications de configuration effectuées ici.