Sites web
Déploiement d'un site à partir de Git
Git Deploy connects a repository to a site so that every push to your chosen branch clones the code, runs your build, and publishes the result. This guide covers the initial connection, the two…
Git Deploy connecte un référentiel à un site de sorte que chaque poussée vers votre branche choisie clone le code, exécute votre build, et publie le résultat. Ce guide couvre la connexion initiale, les deux étapes côté référentiel qui finalisent la configuration, la lecture de l'historique de déploiement, et la détection de buildpack qui décide comment une application Node.js est construite.
Où Git Deploy se trouve
Ouvrez Websites, cliquez sur le site, ouvrez le menu Advanced dans la bande d'onglets du site, et choisissez Git Deploy. Deux pages connexes se trouvent dans le même menu:
- Deploys, l'historique complet des déploiements pour ce site.
- Buildpack, la stratégie de build détectée, sur les sites Node.js.
La page Git Deploy se décrit clairement: connectez un référentiel et chaque poussée vers votre branche configurée déclenche un build et un déploiement.
Connexion d'un référentiel
- Choisissez votre Provider: GitHub, GitLab ou Bitbucket.
- Entrez l'URL du référentiel. Le formulaire SSH est ce que vous voulez, par exemple
git@github.com:user/repo.git. - Définissez la Branch à partir de laquelle déployer. Le champ commence par
main. - Définissez optionnellement une commande de build, par exemple
npm run build. - Définissez optionnellement un répertoire de sortie, par exemple
dist,public, ou.pour un référentiel qui est déjà construit. - Cliquez sur Connect repo.
Laissez la commande de build et le répertoire de sortie vides si votre référentiel est déjà déployable en l'état, ce qui est le cas courant pour un site PHP simple ou statique.
Scripts avancés
L'expansion de Advanced révèle deux champs supplémentaires:
- 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 choses qui doivent se produire une fois que le nouveau code est en place: effacer un cache d'application, exécuter une migration de base de données, redémarrer un worker.
Auto-Deploy lors d'une poussée
Le commutateur au bas de la carte contrôle si les poussées déploient du tout. Quand il est activé, chaque poussée vers la branche configurée déclenche un déploiement. Quand il est désactivé, les déploiements ne s'exécutent que lorsque vous les déclenchez manuellement avec Deploy now.
Désactivez le déploiement automatique lors d'un gel de code ou d'un incident plutôt que de déconnecter le référentiel. La déconnexion supprime la clé de déploiement et le secret webhook, donc vous devez refaire les deux étapes côté référentiel après.
Finalisation de la configuration dans votre référentiel
La connexion du référentiel dans KPanel n'est que la première des trois étapes. Jusqu'à ce qu'un déploiement ait eu lieu, la page affiche une bannière indiquant Complete setup: 2 steps remaining avec tout ce dont vous avez besoin.
Étape 2: Ajouter la clé de déploiement
Kapsule a besoin d'un accès en lecture pour cloner votre référentiel. La bannière affiche une clé publique avec un bouton Copy key.
Collez-la dans les clés de déploiement de votre référentiel. Pour GitHub, la bannière offre un raccourci Add to GitHub directement vers la page de paramètres appropriée. L'accès en lecture est suffisant; n'accordez pas d'accès en écriture.
Étape 3: Ajouter le webhook
Le webhook est ce qui dit à Kapsule qu'une poussée s'est produite. La bannière vous donne trois valeurs:
| Champ | Valeur |
|---|---|
| Payload URL | Une URL se terminant par /api/git-deploy/webhook/ plus 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'oeil |
| Content Type | application/json |
Copiez chacun dans les paramètres webhook de votre référentiel. Pour GitHub, il y a un raccourci Add webhook to GitHub. Définissez le type de contenu sur JSON, pas la valeur par défaut codée en formulaire, ou la charge utile ne s'analysera pas.
Traitez le secret webhook comme un mot de passe. Quiconque le possède, plus l'URL de la charge utile, peut déclencher un déploiement de votre site. Les deux valeurs ne sont affichées que aux personnes qui peuvent déjà administrer le site, et le secret reste masqué derrière l'icône en forme d'oeil jusqu'à ce que vous le demandiez.
Déploiement manuel
Cliquez sur Deploy now sur la page Git Deploy pour construire et déployer l'en-tête actuel de la branche configurée sans pousser un commit. Cela fonctionne que le déploiement automatique soit activé ou non, ce qui en fait l'outil approprié lors d'un gel: les poussées sont ignorées, mais vous pouvez quand même déployer le correctif.
Lecture de l'historique de déploiement
Ouvrez Advanced, puis Deploys. La page est intitulée Deploy history et liste tous les déploiements déclenchés par webhook ou manuellement, les plus récents en premier.
Chaque ligne contient:
- Une icône de statut et le SHA court du commit, avec la branche en tant que pastille.
- Le message de commit, ou Manual deploy s'il n'y avait pas de message de commit à afficher.
- L'auteur, il y a combien de temps il a été exécuté, combien de temps il a pris, et ce qui l'a déclenché.
- Une pastille de statut.
Les statuts sont pending, building, deploying, success et failed. Tant que quoi que ce soit est en cours, la page se rafraîchit toutes les cinq secondes et affiche une note Refreshing automatically sous le tableau, de sorte que vous pouvez la laisser ouverte et regarder un déploiement se terminer.
Quand un déploiement échoue
Une ligne échouée obtient un bouton Error à droite. Cliquez dessus pour développer la sortie d'erreur capturée en ligne, sans quitter la page. Cette sortie est le propre texte d'erreur du build, donc il nomme généralement le fichier ou la commande qui a échoué.
Travaillez à travers cela dans cet ordre: lisez l'erreur, reproduisez la même commande de build localement, corrigez, poussez. Si le build fonctionne localement mais pas ici, la différence est presque toujours une différence d'environnement, une dépendance manquante qui est installée globalement sur votre machine, ou un fichier qui est dans votre répertoire de travail mais pas committé.
Détection de buildpack
Sur les sites Node.js, la page Buildpack dans le menu Advanced affiche comment Kapsule a décidé de construire votre app. La détection s'exécute sur les fichiers à la racine de votre référentiel, et la première correspondance gagne:
| Détecté | Déclencheur |
|---|---|
| Custom buildpack | kapsule.config.yaml ou kapsule.config.yml à la racine |
| Dockerfile buildpack | Dockerfile à la racine |
| Node.js | package.json avec un script start, build ou dev |
| Python | requirements.txt ou pyproject.toml |
| PHP | composer.json |
| Static | index.html à la racine |
Si rien ne correspond, la page le dit et liste les déclencheurs supportés. Ajoutez un Dockerfile ou un kapsule.config.yaml pour prendre le contrôle du build explicitement.
Exécution d'un build
Cliquez sur Run build pour en mettre un en file d'attente. La page interroge toutes les trois secondes tandis qu'une exécution est en cours, et le tableau Recent builds 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 sa queue de journal.
Un seul build peut être en cours à la fois. Déclencher un second tandis qu'un est mis en file d'attente ou en cours est refusé avec A build is already in progress, ce qui est intentionnel: deux builds écrivant la même sortie à la fois, c'est comment vous finissez avec un site partiellement déployé.
Déconnexion
Cliquez sur Disconnect et confirmez. La confirmation est explicite quant au rayon d'impact: 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.
Nettoyez après en supprimant la clé de déploiement et le webhook dans les paramètres de votre référentiel. Ils cesseront simplement de fonctionner, mais laisser des entrées mortes autour rend l'audit suivant plus difficile.
Dépannage
Les poussées ne déclenchent rien. Vérifiez d'abord le commutateur de déploiement automatique, puis le webhook dans votre référentiel. 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 quitté votre référentiel du tout.
Le clonage échoue. La clé de déploiement manque, a été collée avec un saut de ligne, ou a été ajoutée au mauvais référentiel. Copiez-la à nouveau avec le bouton Copy key 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 en attente et ne bouge jamais. Le déploiement a été mis en file d'attente mais n'a jamais été récupéré. Déclenchez un Deploy now manuel et vérifiez la page Deploys pour une ligne d'erreur.
Où aller ensuite
- Preview Deploys For Pull Requests ajoute une URL par PR en haut de cette configuration.
- Storing App Secrets For a Site pour les identifiants dont votre build et runtime ont besoin.
- Site Activity Log enregistre les modifications de configuration faites ici.