Déployer depuis GitHub ou GitLab avec Plesk
Connectez un dépôt GitHub ou GitLab à Plesk, déployez votre site manuellement ou automatiquement à chaque push grâce à un webhook, et corrigez les erreurs les plus fréquentes.
Sur cette page
Vos valeurs
Renseignez-les une fois, les commandes du guide se mettent à jour.
Ce guide explique comment relier un dépôt GitHub ou GitLab à votre site Plesk. Une fois la configuration terminée, un simple git push peut mettre à jour votre site.
Le principe est le suivant : vous envoyez vos modifications vers GitHub ou GitLab, Plesk récupère les nouveaux commits, puis copie les fichiers de la branche active dans le dossier de votre site.
Prérequis
- Un accès à votre panneau Plesk (voir Connexion à l'interface Plesk).
- Un dépôt GitHub ou GitLab contenant votre site.
- Les droits d'administration du dépôt pour ajouter une clé et un webhook. Sur GitLab, il faut le rôle Maintainer ou Owner.
Ce guide utilise httpdocs, le dossier habituel du domaine principal. Pour un domaine supplémentaire, le dossier peut être différent : reportez-vous à la Racine du document dans Hébergement et DNS > Hébergement.
Étape 1 : préparer le dépôt
Le contenu de la racine du dépôt est copié dans le dossier cible, /httpdocs par défaut. Un fichier index.html à la racine du dépôt devient donc httpdocs/index.html.
Ne versionnez jamais vos secrets ni les fichiers générés. Voici un exemple de .gitignore :
.env
node_modules/
vendor/
*.logLes fichiers ignorés par Git ne sont pas déployés. Un fichier .env doit donc être créé directement sur le serveur.
Étape 2 : ajouter le dépôt dans Plesk
- Allez dans Sites Web & Domaines et repérez votre domaine.
- Cliquez sur Git. Si un dépôt existe déjà, cliquez sur Ajouter un dépôt.
- Sélectionnez Hébergement Git distant de type GitHub ou BitBucket. Cette option convient aussi à GitLab.
- Dans le champ du dépôt distant, saisissez l'adresse de votre dépôt.
| Type de dépôt | Format de l'adresse |
|---|---|
| Public | https://github.com/votre-compte/mon-site.git |
| Privé, GitHub | git@github.com:votre-compte/mon-site.git |
| Privé, GitLab | git@gitlab.com:votre-compte/mon-site.git |
Pour un dépôt privé, le format SSH est recommandé : Plesk génère alors une clé et affiche le champ Clé publique SSH. Ne validez pas encore et passez à l'étape 3.
Étape 3 : autoriser Plesk à lire un dépôt privé
Copiez le contenu du champ Clé publique SSH, puis ajoutez-le comme clé de déploiement.
Sur GitHub :
- Ouvrez le dépôt, puis Settings > Deploy keys.
- Cliquez sur Add deploy key.
- Donnez un nom à la clé dans Title, par exemple
Plesk, et collez la clé dans Key. - Laissez Allow write access décoché : Plesk n'a besoin que de lire le dépôt.
- Cliquez sur Add key.
Sur GitLab :
- Ouvrez le projet, puis Settings > Repository.
- Dépliez Deploy keys et sélectionnez Add new key.
- Donnez un nom à la clé et collez-la.
- Laissez Grant write permissions to this key décoché, puis enregistrez.
Étape 4 : choisir le mode de déploiement
De retour dans Plesk, dans la section Votre site Web :
-
Choisissez le Mode de déploiement :
Mode Effet Déploiement automatique Les commits récupérés sont publiés immédiatement Déploiement manuel Les commits sont récupérés, mais publiés seulement lorsque vous le demandez Aucun déploiement (hébergement de dépôt) Rien n'est publié -
Vérifiez le Répertoire cible. Laissez
/httpdocspour un site classique. -
Cliquez sur OK. Plesk clone alors le dépôt.
Pour un site en production, le mode manuel est plus prudent tant que votre processus n'est pas éprouvé : avec le mode automatique, toute erreur poussée sur la branche active est aussitôt en ligne.
Étape 5 : sélectionner la branche et déployer
- Sur la page Git, cliquez sur Modifier la branche et le chemin d'accès.
- Dans Branche, sélectionnez votre branche de production, par exemple
main, puis validez. - Cliquez sur Récupérer les derniers changements.
- En mode manuel, cliquez sur Déployer depuis le dépôt (ou Déployer).
Seule la branche active est déployée.
Étape 6 : automatiser avec un webhook
Sans webhook, Plesk ne sait pas qu'un nouveau commit existe et vous devez cliquer sur Récupérer les derniers changements. Le webhook le prévient à chaque git push.
Dans Plesk, cliquez sur Paramètres du dépôt et copiez l'URL du webhook. Traitez-la comme un secret : toute personne qui la connaît peut déclencher une récupération.
Sur GitHub :
- Ouvrez Settings > Webhooks, puis cliquez sur Add webhook.
- Collez l'adresse dans Payload URL.
- Dans Content type, choisissez
application/json. - Conservez l'envoi de l'événement
pushuniquement (Just the push event). - Vérifiez que Active est coché, puis cliquez sur Add webhook.
Sur GitLab :
- Ouvrez Settings > Webhooks, puis sélectionnez Add new webhook.
- Collez l'adresse dans URL.
- Dans Trigger, cochez Push events.
- Laissez Enable SSL verification activé si le certificat de Plesk est valide.
- Sélectionnez Add webhook.
Étape 7 : lancer des actions après le déploiement
Certains projets ont besoin d'une action après la copie des fichiers, comme relancer une application ou vider un cache.
- Dans Paramètres du dépôt, cochez Activer des actions de déploiement supplémentaires.
- Saisissez une commande par ligne.
Par exemple, pour redémarrer une application Node.js dont le dossier est httpdocs :
cd httpdocs
mkdir -p tmp
touch tmp/restart.txtPour installer les dépendances et compiler ce même projet, en remplaçant 24 par la version de Node.js utilisée :
export PATH=/opt/plesk/node/24/bin:$PATH
cd httpdocs
npm ci
npm run build
mkdir -p tmp
touch tmp/restart.txtPour un projet Laravel, consultez Héberger un site Laravel sur Plesk.
Vérifier le résultat
-
Modifiez un fichier visible, puis envoyez la modification :
Terminalgit add . git commit -m "Test du déploiement" git push origin main -
Dans Plesk, sur la page Git, vérifiez que le dernier commit affiché est le vôtre. Logs de commit présente l'historique.
-
Rechargez
https://votre-domaine.com/et contrôlez la modification. -
Vérifiez la livraison du webhook :
- GitHub : Settings > Webhooks, ouvrez le webhook, puis Recent deliveries ;
- GitLab : Settings > Webhooks, Edit, puis Recent events. Le bouton Test > Push events permet aussi d'envoyer un essai.
Revenir à une version précédente
Annulez le commit fautif, puis poussez le résultat :
git revert HEAD
git push origin mainUn nouveau déploiement rétablit les fichiers. Si des migrations de base de données ont été exécutées, elles ne sont pas annulées par cette opération.
Dépannage
Permission denied (publickey)
La clé publique de Plesk n'a pas été ajoutée au dépôt, ou elle l'a été sur un autre dépôt. Copiez-la de nouveau depuis Plesk et vérifiez la liste des clés de déploiement.
Key is already in use sur GitHub
Cette clé de déploiement est déjà associée à un autre dépôt. Retirez-la de ce dépôt ou ajoutez-la à un compte GitHub dédié.
Repository not found ou Authentication failed
L'adresse est incorrecte, le dépôt est privé alors que vous utilisez une adresse HTTPS sans identifiants, ou le jeton a expiré. L'adresse d'un dépôt ne pouvant pas être modifiée dans Plesk, supprimez-le avec Supprimer le dépôt puis ajoutez-le de nouveau. Les fichiers déjà publiés sont conservés.
Le push n'entraîne aucune mise à jour
Vérifiez dans l'ordre :
- que le commit a été poussé sur la branche active ;
- que le mode n'est pas Déploiement manuel ou Aucun déploiement ;
- que le webhook a bien été reçu, dans l'historique de GitHub ou GitLab.
Le webhook échoue avec une erreur de certificat
Si le panneau Plesk utilise un certificat auto-signé, la connexion HTTPS peut échouer. Plesk recommande alors d'utiliser http:// au début de l'URL du webhook. L'URL circulant ensuite sans chiffrement, privilégiez cette solution uniquement de manière temporaire et signalez le problème au support.
GitLab indique que le webhook est désactivé
GitLab désactive temporairement un webhook après quatre échecs consécutifs, puis définitivement après quarante. Corrigez la cause, puis envoyez un test réussi pour le réactiver.
Des fichiers ont disparu du site
Un fichier supprimé du dépôt est aussi supprimé du site lors du déploiement. Stockez les fichiers envoyés par vos utilisateurs dans un dossier non versionné, et restaurez les fichiers perdus depuis une sauvegarde.
Le répertoire cible est refusé
Deux dépôts d'un même domaine ne peuvent pas partager le même dossier de déploiement. Choisissez un autre Répertoire cible.
L'ancienne page reste affichée
Un fichier index.html peut être prioritaire sur votre index.php, notamment la page créée par défaut par Plesk. Supprimez-le de httpdocs s'il n'appartient pas à votre projet, puis videz le cache de votre navigateur.
npm: command not found dans les actions de déploiement
Le chemin des outils n'est pas chargé dans ce contexte. Ajoutez la ligne export PATH=/opt/plesk/node/24/bin:$PATH en adaptant la version. Si l'erreur persiste, l'environnement est probablement chrooté.