Déployer Laravel depuis GitHub avec Git et le .cpanel.yml de cPanel

Ce guide explique le flux manuel avec Git et le .cpanel.yml de cPanel pour une application Laravel. Si vous voulez gérer dépôts, scripts, versions et webhooks depuis l'espace client, utilisez Deploy+.

L'exemple de cPanel met à jour un clone de travail. Il ne crée pas à lui seul de releases isolées et ne garantit pas que le site reste disponible sans interruption pendant une mise à jour.

Préparer l'accès et le projet

Activez SSH et préparez une clé dédiée en lecture seule pour le dépôt privé. Vérifiez l'empreinte de GitHub et évitez de réutiliser une identité qui a accès à d'autres projets.

Travaillez d'abord avec un domaine et une base de données de test. Le dépôt doit inclure le code et composer.lock, mais ni mots de passe, ni .env de production, ni fichiers envoyés par les utilisateurs.

Dans cPanel > Git Version Control > Create, saisissez l'URL SSH, un chemin privé comme ~/repositories/laravel (remplacez ~ par le répertoire de votre compte si le formulaire exige un chemin absolu) et un nom pour l'identifier. Si vous utilisez un alias SSH pour la clé, employez-le aussi dans l'URL du clone.

Vérifiez la branche et le contenu avant de configurer le déploiement.

Définir les tâches

Créez .cpanel.yml à la racine du dépôt. Pour regrouper les vérifications et arrêter le processus si une commande échoue, appelez un script versionné :

---
deployment:
  tasks:
    - /bin/bash /home/usuario_cpanel/repositories/laravel/deploy/cpanel.sh

Voici un exemple de deploy/cpanel.sh :

#!/bin/bash
set -euo pipefail
cd /home/usuario_cpanel/repositories/laravel

PHP_BIN=/opt/alt/php83/usr/bin/php
COMPOSER_BIN=/opt/cpanel/composer/bin/composer

test -x "$PHP_BIN"
test -f "$COMPOSER_BIN"
test -f composer.lock
test -f .env

"$PHP_BIN" "$COMPOSER_BIN" install --no-dev --no-interaction --prefer-dist --optimize-autoloader
"$PHP_BIN" artisan config:cache
"$PHP_BIN" artisan view:cache
"$PHP_BIN" artisan route:cache

Remplacez l'utilisateur et vérifiez les chemins de PHP et de Composer dans votre compte. PHP 8.3 n'est que la valeur de l'exemple : l'interpréteur en ligne de commande doit être compatible avec votre application et avec la version qui sert le site. N'utilisez pas composer update pour résoudre les dépendances directement en production.

Préparez le .env privé, la base de données et les répertoires persistants avant d'exécuter le script. Si vous migrez une application existante, conservez son APP_KEY. Configurez APP_DEBUG=false. Ajoutez la compilation des ressources dont le projet a besoin, ou publiez-les déjà compilées depuis un environnement compatible.

Les migrations de base de données ont besoin de leur propre plan testé. Elles ne sont pas incluses automatiquement ici : une erreur dans le code n'annule pas une migration et ne récupère pas les données.

Publier uniquement le dossier public

Laravel doit être exposé par son dossier public, et non par la racine du dépôt. Vérifiez la racine du document du domaine et les chemins que le serveur autorise.

Pour un domaine supplémentaire ou un sous-domaine, utilisez un chemin accepté par cPanel. Si le domaine principal doit conserver public_html, préparez la publication adéquate avec l'assistance ou avec l'outil de déploiement. Ne supprimez pas et ne renommez pas tout ce dossier sans vérifier les autres sites, fichiers et services qui en dépendent.

Avant de changer la publication, sauvegardez le site et la base de données et prévoyez comment revenir à la destination précédente. Testez d'abord le projet à son emplacement d'essai.

Mettre à jour et déployer

Dans le dépôt de cPanel, ouvrez Manage > Pull or Deploy :

1. Lancez Update from Remote pour récupérer le code.
2. Vérifiez le commit et la branche.
3. Lancez Deploy HEAD Commit pour les tâches de .cpanel.yml.
4. Suivez le journal jusqu'à la fin et testez le site.

Mettre à jour depuis le dépôt distant et exécuter les tâches sont deux opérations distinctes. Si le site sert directement le clone, la première étape peut déjà modifier des fichiers visibles même si vous n'avez pas encore lancé la seconde.

La requête équivalente de déploiement local est :

/usr/local/cpanel/bin/uapi --output=jsonpretty VersionControlDeployment create \
  repository_root='/home/usuario_cpanel/repositories/laravel'

Un result.status égal à 1 confirme que cPanel a accepté la demande. Consultez la tâche et son log_path jusqu'à connaître le résultat final ; ne l'interprétez pas comme « l'application fonctionne déjà ».

Automatiser sans chevauchement de tâches

Un push vers GitHub ne lance pas à lui seul le pull de cPanel. Pour l'automatiser, il vous faut un récepteur ou un processus qui le programme. Deploy+ offre cette intégration sans avoir à construire le récepteur.

Si vous gérez le vôtre, validez la signature du fournisseur, le dépôt et la branche avant de mettre une tâche en file d'attente. Utilisez des commandes et des chemins définis dans votre configuration, et maintenez un verrou jusqu'à la fin réelle du déploiement. Verrouiller seulement l'appel qui met une tâche en file d'attente n'empêche pas deux tâches suivantes de se chevaucher.

Ne publiez pas d'URL qui exécute des commandes lorsqu'on la visite et n'injectez pas le contenu du webhook directement dans le shell. Enregistrez la livraison, le commit et le résultat sans secrets.

Valider et récupérer

Testez la page d'accueil, une route dynamique, l'authentification, les formulaires et les ressources. Vérifiez les journaux et les processus qui doivent charger le nouveau code. Si le déploiement échoue, identifiez les tâches qui ont été exécutées avant de le relancer.

Récupérer un répertoire ou un commit précédent ne restaure ni les bases de données, ni le .env, ni les fichiers partagés. Pour des mises à jour fréquentes qui nécessitent d'alterner entre versions, envisagez Deploy+ ou une stratégie de releases avec un retour en arrière testé.