Sites web
Aperçu des déploiements pour les demandes de tirage
Preview deploys give every pull request its own live URL, built from that branch's code, so reviewers can click through the actual change instead of reading a diff and guessing. Each preview updates…
Les déploiements en aperçu donnent à chaque demande de tirage sa propre URL en direct, construite à partir du code de cette branche, afin que les relecteurs puissent cliquer sur la modification réelle au lieu de lire une différence et de deviner. Chaque aperçu se met à jour lorsque vous envoyez un nouveau commit et est nettoyé automatiquement lorsque la demande de tirage ferme.
Où vivent les déploiements en aperçu
Ouvrez Websites, cliquez sur le site, ouvrez le menu Environments dans la bande d'onglets du site, et choisissez Preview. La page s'intitule Preview deploys.
Les aperçus sont séparés de la mise en scène. La mise en scène est une seule copie à long terme du site que vous envoyez délibérément ; un aperçu est un environnement éphémère créé par demande de tirage et supprimé ensuite. De nombreuses équipes utilisent les deux. Voir Staging Environments pour l'autre moitié.
Configurez d'abord Git Deploy
Les aperçus ne sont pas une fonctionnalité autonome. Ils réutilisent la clé de déploiement et la commande de compilation du site de production, le site doit donc avoir une configuration Git Deploy fonctionnelle avant que les aperçus puissent être activés.
Si Git Deploy n'est pas configuré, la page affiche Set up Git deploy first et propose un bouton Go to Git deploy plutôt que le formulaire d'activation. Travaillez sur Deploying a Site From Git, puis revenez.
Si Git Deploy est connecté mais n'a pas de commande de compilation, la page Preview affiche un avertissement. Les aperçus supposeront que le référentiel est déjà construit, avec des fichiers statiques à la racine. C'est correct pour un site HTML brut et incorrect pour tout ce qui compile, définissez donc une commande de compilation sur la page Git Deploy si votre projet en a besoin.
Activation des aperçus
- Dans la carte Enable preview deploys, tapez le référentiel au format
owner/repo. Pas une URL, pas une adresse SSH : juste les deux segments, par exempleacme/marketing-site. - Cliquez sur Enable.
Tout ce qui ne correspond pas à owner/name est rejeté avec Repo must be in owner/name format.
Immédiatement après l'activation, KPanel affiche le secret de signature du webhook dans une carte intitulée Copy your webhook secret now, avec un avertissement selon lequel vous ne le verrez plus jamais.
Copiez le secret avant de quitter la page. Il est généré une seule fois et ne peut pas être récupéré par la suite. Si vous le perdez, la solution consiste à le régénérer, ce qui invalide l'ancien et signifie mettre à jour votre webhook de référentiel de toute façon.
Ajout du webhook à votre référentiel
La carte configurée affiche une Webhook URL à coller dans les paramètres de votre référentiel, sous Webhooks. Configurez-la avec :
- Payload URL : l'URL du webhook affichée sur la page.
- Secret : la valeur que vous venez de copier.
- Content type : JSON.
- Events : événements de demande de tirage, plus les envois, afin que les nouveaux commits sur une demande de tirage ouverte reconstruisent l'aperçu.
Une fois cela en place, l'ouverture d'une demande de tirage construit un aperçu dans quelques minutes. Un travail en arrière-plan vérifie s'il y a du nouveau travail d'aperçu toutes les minutes, il n'est donc pas nécessaire d'appuyer sur quoi que ce soit dans KPanel.
URLs d'aperçu
Chaque aperçu obtient son propre nom d'hôte sous la forme pr-<pull-request-number>-<site-id>.kapsulecloud.app, couvert par un certificat wildcard afin qu'il soit servi via HTTPS sans aucune étape de certificat de votre part.
Le moyen fiable d'en ouvrir un est le bouton Open sur la ligne de l'aperçu dans Recent previews, qui porte l'URL exacte qui a été fournie pour cette compilation. Collez ce lien dans la demande de tirage afin que les relecteurs n'aient pas besoin de trouver KPanel du tout.
Lecture de la liste des aperçus récents
La section Recent previews liste les aperçus les plus récents, les plus récents en premier. Chaque ligne affiche le numéro et le titre de la demande de tirage, la branche, le commit et un statut :
| Status | Meaning |
|---|---|
| BUILDING | Clone et compilation en cours |
| LIVE | Servir à son URL d'aperçu |
| FAILED | La compilation a échoué ; développez le journal pour voir pourquoi |
| DESTROYED | Nettoyé, généralement parce que la demande de tirage a fermé |
Cliquez sur Toggle build log sur une ligne pour développer sa sortie de compilation en ligne. Ce journal est le premier endroit où regarder quand un aperçu échoue, et c'est le même résultat que votre compilation produirait localement.
Si la liste est vide, la page le dit : ouvrez une demande de tirage sur le référentiel et un aperçu sera construit dans quelques minutes.
Rotation du secret du webhook
Cliquez sur Regenerate secret dans la carte configurée. KPanel vous demande de confirmer, et précise que le secret actuel cesse de fonctionner immédiatement et que vous devrez le mettre à jour dans les paramètres du webhook de votre référentiel par la suite.
Le nouveau secret est affiché une seule fois, dans la même carte unique qu'avant. Copiez-le, puis mettez à jour le webhook dans votre référentiel. Entre ces deux moments, les livraisons de webhook entrantes sont rejetées, faites donc les deux étapes l'une après l'autre.
Régénérez le secret quand quelqu'un ayant accès à l'administrateur du référentiel s'en va, ou si le secret a jamais été collé quelque part où il ne devrait pas être, comme un canal de chat partagé ou un ticket.
Désactivation des aperçus
Cliquez sur Disable. La configuration est désactivée et le secret stocké est effacé. Les aperçus existants cessent d'être reconstruits.
Nettoyez en supprimant également le webhook de votre référentiel. Il commencera à échouer plutôt que de faire quelque chose de nuisible, mais un webhook qui retourne des erreurs à jamais est du bruit dans le journal de livraison de votre référentiel.
Coûts et entretien
Les aperçus construisent et servent du code réel, ils utilisent donc les mêmes ressources que tout autre déploiement sur le site. Deux habitudes le gardent sous contrôle :
- Fermez les demandes de tirage sur lesquelles vous n'êtes plus en train de travailler. Une demande de tirage fermée a son aperçu nettoyé automatiquement.
- Ne pointez pas les aperçus vers les identifiants de production. Donnez-leur des clés de test via l'onglet Secrets de l'environnement preview, qui existe précisément pour que la configuration de prévisualisation et de production ne puisse pas être confuse.
Une URL d'aperçu n'est pas privée. C'est un vrai nom d'hôte accessible publiquement avec un certificat valide, et n'importe qui qui a le lien peut l'ouvrir. N'utilisez pas un aperçu pour examiner quoi que ce soit contenant des données client réelles, et ne mettez pas en amorce les environnements d'aperçu à partir d'une copie de base de données de production.
Dépannage
Rien n'est construit lorsqu'une demande de tirage est ouverte. Vérifiez les livraisons récentes du webhook dans votre référentiel. Un 401 ou 403 signifie que le secret ne correspond pas, régénérez-le et mettez à jour les deux extrémités. Aucune livraison du tout signifie que le webhook n'est pas abonné aux événements de demande de tirage.
L'aperçu se construit mais affiche un listage de répertoire ou un 404. Le répertoire de sortie sur la page Git Deploy ne correspond pas à l'endroit où votre compilation écrit réellement. Les aperçus héritent ce paramètre de la production.
La compilation échoue seulement dans l'aperçu. La cause la plus courante est une dépendance ou une variable d'environnement qui existe en production mais n'a jamais été ajoutée à l'environnement d'aperçu. Vérifiez l'onglet preview sur la page Secrets.
Une URL d'aperçu cesse de fonctionner. Regardez le statut sur sa ligne. DESTROYED signifie que la demande de tirage a fermé et que l'environnement a été réclamé, ce qui est le comportement prévu.
Où aller ensuite
- Deploying a Site From Git, la configuration préalable.
- Storing App Secrets For a Site pour les identifiants par environnement.
- Staging Environments pour une copie pré-production persistante.