# Déploiements de prévisualisation pour les pull requests

Source: https://support.kapsulehost.com/fr-fr/site-preview

Les déploiements de prévisualisation donnent à chaque pull request sa propre URL en direct, construite à partir du code de cette branche, afin que les relecteurs puissent parcourir le changement réel au lieu de lire un diff en devinant. Chaque prévisualisation se met à jour lorsque vous poussez un nouveau commit et est nettoyée automatiquement à la fermeture de la pull request.

## Où vivent les déploiements de prévisualisation

Ouvrez **Sites web**, cliquez sur le site, ouvrez le groupe **Environment** dans le menu de gauche du site, et choisissez **Aperçu**. La page s'intitule **Déploiements de prévisualisation**.

Les prévisualisations sont distinctes du staging. Le staging est une copie du site longue durée que vous mettez à jour délibérément ; une prévisualisation est un environnement éphémère créé pour chaque pull request et jeté ensuite. De nombreuses équipes utilisent les deux. Voir [Environnements de staging](https://support.kapsulehost.com/fr-fr/staging-environments) pour l'autre moitié.

![The Preview deploys page for a site in KPanel](https://support.kapsulehost.com/help/screenshots/site-preview.0fb977c9.webp)

## Configurez d'abord le déploiement Git

Les prévisualisations ne sont pas une fonctionnalité autonome. Elles réutilisent la clé de déploiement et la commande de build du site de production, le site doit donc disposer d'une configuration Git Deploy fonctionnelle avant que les prévisualisations puissent être activées.

Si Git Deploy n'est pas configuré, la page affiche **Configurez d'abord le déploiement Git** et propose un bouton **Aller au déploiement Git** plutôt que le formulaire d'activation. Suivez [Déployer un site depuis Git](https://support.kapsulehost.com/fr-fr/site-git-deploy), puis revenez.

> **Note:** Si Git Deploy est connecté mais n'a pas de commande de build, la page Preview affiche un avertissement. Les prévisualisations supposeront que le dépôt est déjà construit, avec des fichiers statiques à la racine. C'est correct pour un site HTML simple et incorrect pour tout ce qui nécessite une compilation, donc définissez une commande de build sur la page Git Deploy si votre projet en a besoin.

## Activation des prévisualisations

1. Dans la carte **Activer les déploiements de prévisualisation**, saisissez le dépôt au format `owner/repo`. Pas une URL, pas une adresse SSH : juste les deux segments, par exemple `acme/marketing-site`.
2. Cliquez sur **Enable**.

Tout ce qui ne correspond pas à `owner/name` est rejeté avec **Le dépôt doit être au format owner/name**.

Immédiatement après l'activation, KPanel affiche le secret de signature du webhook dans une carte intitulée **Copiez votre secret de webhook maintenant**, avec un avertissement indiquant que vous ne le reverrez plus.

> **Important:** Copiez le secret avant de quitter la page. Il est généré une seule fois et n'est pas récupérable par la suite. Si vous le perdez, la solution consiste à le régénérer, ce qui invalide l'ancien et oblige à mettre à jour le webhook de votre dépôt de toute façon.

## Ajout du webhook à votre dépôt

La carte configurée affiche une **URL du webhook** à coller dans les paramètres de votre dépôt, sous Webhooks. Configurez-la avec :

- **URL du payload** : l'URL du webhook affichée sur la page.
- **Secret** : la valeur que vous venez de copier.
- **Type de contenu** : JSON.
- **Événements** : les événements de pull request, plus les push, afin que les nouveaux commits sur une pull request ouverte reconstruisent la prévisualisation.

Une fois cela en place, l'ouverture d'une pull request construit une prévisualisation en quelques minutes. Une tâche en arrière-plan vérifie le nouveau travail de prévisualisation chaque minute, il n'est donc pas nécessaire d'appuyer sur quoi que ce soit dans KPanel.

## URL de prévisualisation

Chaque prévisualisation obtient son propre nom d'hôte de la forme `pr-<pull-request-number>-<site-id>.kapsulecloud.app`, couvert par un certificat wildcard, elle est donc servie en HTTPS sans aucune étape de certificat de votre part.

La manière fiable d'en ouvrir une est le bouton **Open** sur la ligne de la prévisualisation dans **Previews récentes**, qui porte l'URL exacte provisionnée pour ce build. Collez ce lien dans la pull request afin que les relecteurs n'aient pas du tout à chercher KPanel.

## Lecture de la liste des previews récentes

La section **Previews récentes** liste les prévisualisations les plus récentes, les plus récentes en premier. Chaque ligne affiche le numéro et le titre de la pull request, la branche, le commit, et un statut :

| Statut | Signification |
|---|---|
| BUILDING | Clonage et construction en cours |
| LIVE | Diffusion en cours sur son URL de prévisualisation |
| FAILED | Le build a échoué ; développez le journal pour voir pourquoi |
| DESTROYED | Nettoyé, généralement parce que la pull request s'est fermée |

Cliquez sur **Basculer le journal de build** sur une ligne pour développer sa sortie de build en ligne. Ce journal est le premier endroit à consulter lorsqu'une prévisualisation échoue, et c'est la même sortie que celle que votre build produirait localement.

Si la liste est vide, la page l'indique : ouvrez une pull request sur le dépôt et une prévisualisation sera construite en quelques minutes.

## Rotation du secret de webhook

Cliquez sur **Régénérer le secret** dans la carte configurée. KPanel vous demande de confirmer, et précise explicitement que le secret actuel cesse de fonctionner immédiatement et que vous devrez le mettre à jour ensuite dans les paramètres de webhook de votre dépôt.

Le nouveau secret est affiché une seule fois, dans la même carte à usage unique que précédemment. Copiez-le, puis mettez à jour le webhook dans votre dépôt. 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 lorsqu'une personne ayant un accès administrateur au dépôt quitte l'équipe, ou si le secret a été collé quelque part où il n'aurait pas dû l'être, comme un canal de discussion partagé ou un ticket.

## Désactiver les prévisualisations

Cliquez sur **Disable**. La configuration est désactivée et le secret stocké est effacé. Les prévisualisations existantes cessent d'être reconstruites.

Faites également le ménage en supprimant le webhook dans votre dépôt. Il commencera à échouer plutôt que de faire quoi que ce soit de nuisible, mais un webhook qui renvoie des erreurs indéfiniment est du bruit dans le journal de livraison de votre dépôt.

## Coûts et entretien

Les prévisualisations construisent et servent du code réel, elles utilisent donc les mêmes ressources que n'importe quel autre déploiement sur le site. Deux habitudes permettent de garder cela sous contrôle :

- Fermez les pull requests sur lesquelles vous ne travaillez plus. Une pull request fermée voit sa prévisualisation nettoyée automatiquement.
- Ne faites pas pointer les prévisualisations vers des identifiants de production. Donnez-leur des clés de test via l'environnement **preview** de l'onglet [Secrets](https://support.kapsulehost.com/fr-fr/site-secrets), qui existe précisément pour que la configuration de prévisualisation et de production ne puisse pas être confondue.

> **Warning:** Une URL de prévisualisation n'est pas privée. C'est un nom d'hôte réel, accessible publiquement, avec un certificat valide, et quiconque possède le lien peut l'ouvrir. N'utilisez pas une prévisualisation pour relire quoi que ce soit contenant de vraies données clients, et n'alimentez pas les environnements de prévisualisation à partir d'un dump de base de données de production.

## Dépannage

**Rien n'est construit lorsqu'une pull request est ouverte.** Vérifiez les livraisons récentes du webhook dans votre dépôt. Un code 401 ou 403 signifie que le secret ne correspond pas, régénérez-le donc et mettez à jour les deux côtés. Aucune livraison du tout signifie que le webhook n'est pas abonné aux événements de pull request.

**La prévisualisation se construit mais affiche une liste de répertoire ou une erreur 404.** Le répertoire de sortie sur la page Git Deploy ne correspond pas à l'endroit où votre build écrit réellement. Les prévisualisations héritent de ce paramètre depuis la production.

**Le build échoue uniquement en prévisualisation.** La cause la plus courante est une dépendance ou une variable d'environnement qui existe en production mais qui n'a jamais été ajoutée à l'environnement de prévisualisation. Vérifiez l'onglet **preview** sur la page Secrets.

**Une URL de prévisualisation cesse de fonctionner.** Regardez le statut sur sa ligne. **DESTROYED** signifie que la pull request s'est fermée et que l'environnement a été récupéré, ce qui est le comportement prévu.

## Pour aller plus loin

- [Déployer un site depuis Git](https://support.kapsulehost.com/fr-fr/site-git-deploy), la configuration préalable.
- [Stocker des secrets d'application pour un site](https://support.kapsulehost.com/fr-fr/site-secrets) pour les identifiants par environnement.
- [Environnements de staging](https://support.kapsulehost.com/fr-fr/staging-environments) pour une copie persistante de pré-production.