Déployer Laravel sur un VPS avec GitHub Actions : zéro downtime et rollback

29 Oct 2026 | Informatique et Technologie

Déployer Laravel sur un VPS avec GitHub Actions : zéro downtime et rollback

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 releases et shared, puis placez-y le .env de 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