Déployer Laravel sur un VPS avec GitHub Actions : zéro downtime et rollback
29 Oct 2026 | Informatique et Technologie
Déployer une application Laravel à la main (connexion SSH, git pull, composer install, migrations) fonctionne… jusqu'au jour où une étape est oubliée en production. Automatiser le déploiement avec GitHub Actions rend le processus reproductible, traçable et réversible. Voici une méthode complète pour un VPS classique.
Principe : des releases versionnées
Au lieu d'écraser le dossier de l'application, on dépose chaque version dans un dossier daté et on bascule un lien symbolique :
/var/www/monapp/
├── releases/
│ ├── 20261024120000/
│ └── 20261025093000/
├── shared/
│ ├── .env
│ └── storage/
└── current -> releases/20261025093000
Le serveur web pointe vers current/public. Basculer vers une nouvelle version, ou revenir en arrière, se résume à changer la cible du lien : c'est quasi instantané, d'où le « zéro downtime ». Le fichier .env et le dossier storage restent dans shared et sont reliés à chaque release.
1. Préparer le serveur
- Créez un utilisateur dédié au déploiement, sans droits administrateur.
- Générez une paire de clés SSH propre au déploiement et ajoutez la clé publique à cet utilisateur.
- Créez l'arborescence
releasesetshared, puis placez-y le.envde production. - Configurez le serveur web (Nginx ou Apache) pour pointer vers
current/public. - Appliquez la checklist de sécurité Laravel avant d'ouvrir le serveur au public.
2. Stocker les secrets dans GitHub
Dans les paramètres du dépôt, ajoutez des secrets : l'hôte, l'utilisateur, la clé privée SSH et le chemin de l'application. Ne les écrivez jamais dans le workflow.
3. Le workflow GitHub Actions
name: Deploy
on:
push:
branches: [main]
jobs:
tests:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: shivammathur/setup-php@v2
with:
php-version: '8.3'
- run: composer install --no-interaction --prefer-dist
- run: cp .env.example .env && php artisan key:generate
- run: php artisan test
deploy:
needs: tests
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: shivammathur/setup-php@v2
with:
php-version: '8.3'
- run: composer install --no-dev --optimize-autoloader --no-interaction
- uses: actions/setup-node@v4
with:
node-version: 20
- run: npm ci && npm run build
- name: Préparer la clé SSH
run: |
mkdir -p ~/.ssh
echo "${{ secrets.SSH_KEY }}" > ~/.ssh/id_deploy
chmod 600 ~/.ssh/id_deploy
ssh-keyscan -H ${{ secrets.SSH_HOST }} >> ~/.ssh/known_hosts
- name: Envoyer la release
run: |
RELEASE=$(date +%Y%m%d%H%M%S)
echo "RELEASE=$RELEASE" >> $GITHUB_ENV
rsync -az --delete -e "ssh -i ~/.ssh/id_deploy" \
--exclude='.git' --exclude='node_modules' --exclude='tests' \
./ ${{ secrets.SSH_USER }}@${{ secrets.SSH_HOST }}:${{ secrets.APP_PATH }}/releases/$RELEASE/
- name: Activer la release
run: |
ssh -i ~/.ssh/id_deploy ${{ secrets.SSH_USER }}@${{ secrets.SSH_HOST }} bash -s <<'EOF'
set -e
cd ${{ secrets.APP_PATH }}
R=releases/${{ env.RELEASE }}
ln -sfn ../../shared/.env $R/.env
rm -rf $R/storage && ln -sfn ../../shared/storage $R/storage
cd $R
php artisan migrate --force
php artisan config:cache
php artisan route:cache
php artisan view:cache
cd ../..
ln -sfn $R current
# Garder les 5 dernières releases
ls -1dt releases/* | tail -n +6 | xargs -r rm -rf
EOF
Ce pipeline lance d'abord les tests ; si l'un échoue, rien n'est déployé. La compilation des assets et l'installation des dépendances se font sur le runner GitHub, pas sur votre serveur, qui reste léger.
4. Gérer les migrations avec prudence
Lancer migrate --force avant la bascule est pratique, mais attention : pendant quelques secondes, l'ancien code tourne sur le nouveau schéma. Adoptez donc des migrations rétrocompatibles : ajoutez une colonne avant de l'utiliser, ne supprimez une colonne qu'une release après avoir cessé de la lire. Sans cette discipline, le rollback du code ne suffira pas à réparer la base.
5. Redémarrer les processus
Après la bascule, relancez les workers et le PHP-FPM pour vider l'opcache :
php artisan queue:restart
sudo systemctl reload php8.3-fpm
Si vous utilisez Horizon, exécutez plutôt php artisan horizon:terminate (voir notre guide sur les files d'attente et Horizon). Pensez à autoriser le rechargement de PHP-FPM via sudoers pour l'utilisateur de déploiement, limité à cette seule commande.
6. Faire un rollback
Le retour arrière tient en une commande, à lancer sur le serveur :
cd /var/www/monapp
ln -sfn releases/<ancienne-release> current
php artisan queue:restart
Vous pouvez en faire un workflow GitHub Actions déclenché manuellement (workflow_dispatch) pour ne plus avoir à vous connecter en SSH.
Bonnes pratiques
- Protégez la branche
main: pas de déploiement sans passage des tests. - Utilisez un environnement GitHub avec approbation manuelle pour la production.
- Surveillez le déploiement : un simple appel à une route de santé après la bascule détecte les erreurs.
- Sauvegardez la base avant les migrations sensibles.
- Restreignez la clé SSH de déploiement à cet usage unique.
Conclusion
Un pipeline GitHub Actions avec releases versionnées transforme le déploiement en une opération banale : un git push, des tests, une bascule de lien symbolique. Le gain n'est pas seulement le temps économisé, c'est surtout la confiance de pouvoir revenir en arrière en quelques secondes. Pour compléter la démarche, pensez à tester vos parcours critiques avec Playwright dans la même pipeline. Si vous préparez une bascule depuis WordPress, lisez aussi notre guide de migration vers Laravel.
Commentaires (0)
Aucun commentaire pour le moment.
Laissez un commentaire