Comment utiliser GitHub Actions pour déployer automatiquement son site

Déployer un site ou une application à la main peut vite devenir répétitif. À chaque mise à jour, il faut se connecter au serveur en SSH, lancer un git pull, installer d’éventuelles dépendances, puis redémarrer l’application. Cette méthode fonctionne, mais elle prend du temps et augmente le risque d’erreur : mauvaise branche déployée, commande oubliée, service non relancé ou fichier modifié directement sur le serveur.✨

Avec GitHub Actions, il est possible d’automatiser ce processus et de déclencher un déploiement automatique à chaque push sur la branche principale. 😊Ce tutoriel vous guide pas à pas pour mettre en place un workflow YAML GitHub Actions capable de se connecter à un VPS LWS via SSH, récupérer le nouveau code et relancer l’application de façon plus fiable, plus rapide et plus sécurisée.

Objectif

👇L’objectif de ce guide est de vous aider à configurer un pipeline simple de CI/CD avec GitHub Actions pour déployer automatiquement votre site ou votre application sur un VPS Linux. À la fin du tutoriel, chaque modification envoyée sur la branche main de votre dépôt GitHub déclenchera un workflow de déploiement. Celui-ci se connectera à votre serveur avec une clé SSH dédiée, utilisera des secrets GitHub pour protéger les informations sensibles, exécutera les commandes nécessaires sur le VPS, puis redémarrera l’application. ⚡Le but n’est pas de remplacer un déploiement initial, mais d’automatiser les mises à jour d’un projet déjà installé une première fois sur le serveur. Vous gagnerez ainsi du temps, tout en réduisant les manipulations manuelles et les erreurs de mise en production.

Pré-requis

Avant de commencer, vous devez disposer :

• d’un dépôt GitHub contenant le code de votre site ou de votre application. Le dépôt peut être public ou privé : dans les deux cas, GitHub Actions pourra exécuter un workflow dès lors que celui-ci est correctement configuré dans le projet.
• Accès à un VPS Linux, idéalement un VPS KVM LWS, avec une connexion SSH fonctionnelle. Ce tutoriel part du principe que votre application a déjà été déployée manuellement au moins une fois. Autrement dit, le serveur doit déjà contenir le projet, cloné avec Git, par exemple dans un dossier comme /var/www/monsite.
• Il est aussi nécessaire d’avoir quelques bases en Git et en ligne de commande : savoir créer un commit, pousser du code avec git push, naviguer dans un terminal Linux et comprendre la notion de branche principale, généralement appelée main.
• Vous n’avez en revanche pas besoin de connaître GitHub Actions avant de lire ce guide. Les notions essentielles seront expliquées progressivement.

Qu’est-ce que GitHub Actions : en une explication claire

GitHub Actions est un outil d’intégration continue et de déploiement continu directement intégré à GitHub. Il permet d’automatiser des actions à partir d’événements qui se produisent dans un dépôt : un push, une pull request, la création d’un tag, ou encore une exécution planifiée à une date précise.

Dans le cadre de ce tutoriel, l’objectif est simple : lorsqu’un développeur pousse du code sur la branche main, GitHub lance automatiquement un workflow. Ce workflow se connecte ensuite au VPS en SSH, récupère la dernière version du code et redémarre l’application. Cette logique évite d’avoir à refaire les mêmes commandes à la main à chaque mise à jour.

Un workflow GitHub Actions est défini dans un fichier au format YAML. Ce fichier indique quand l’automatisation doit se déclencher, sur quelle machine elle doit s’exécuter, et quelles étapes doivent être réalisées. C’est ce fichier que nous allons créer plus loin dans ce tutoriel.

Voici le vocabulaire essentiel à connaître avant de passer à la configuration :

La force de GitHub Actions est son intégration native avec GitHub. Vous n’avez pas besoin d’installer un outil externe pour commencer. Il suffit d’ajouter un fichier dans le dépôt, puis de suivre les exécutions depuis l’onglet « Actions ».

Ce tutoriel couvre un cas précis : le déploiement automatique d’une application déjà hébergée sur un VPS, via une connexion SSH déclenchée à chaque push. Nous allons donc nous concentrer sur une approche simple, adaptée à un développeur qui gère son code sur GitHub et souhaite automatiser la mise en production sur son propre serveur.

En revanche, nous n’aborderons pas ici les pipelines complexes avec plusieurs environnements séparés, les runners auto-hébergés ou les stratégies avancées de tests automatisés. Pour comparer cette approche avec une solution auto-hébergée, vous pouvez aussi découvrir une alternative auto-hébergée avec GitLab CI/CD/.

Besoin d’un serveur VPS KVM performant et flexible ?

Découvrez nos offres VPS KVM haut de gamme : des ressources garanties et un contrôle total pour vos projets. Profitez d’un hébergement 100 % SSD, d’un accès root complet, le tout dans un datacenter en France. Démarrez dès maintenant à partir de 4,99 €/mois !

Je choisis mon VPS KVM

Créer un snapshot LWS avant de commencer

Avant de connecter GitHub Actions à votre serveur, il est recommandé de créer un snapshot de votre VPS LWS. Cette étape est souvent négligée, mais elle apporte une sécurité importante lors de la mise en place d’un déploiement automatique.

Un snapshot correspond à une copie de l’état de votre serveur à un instant précis. Si une erreur de configuration provoque un problème lors du premier déploiement, vous pouvez revenir rapidement à une version stable du VPS, sans devoir tout réinstaller manuellement.

Depuis votre espace client, rendez-vous dans le LWS Panel KVM, puis dans la rubrique « Snapshots ».

Cliquez ensuite sur le bouton  « Créer un snapshot ».

Donnez-lui un nom explicite, par exemple avant-github-actions.

Cette précaution est particulièrement utile lorsque vous modifiez la façon dont votre serveur reçoit du code. Avec un workflow automatisé, une mauvaise commande dans le fichier YAML peut être exécutée à distance sur le VPS. Le snapshot vous permet donc de tester plus sereinement la configuration, surtout lors du premier essai.

Gardez toutefois en tête qu’un snapshot ne remplace pas une vraie stratégie de sauvegarde. Il s’agit ici d’un filet de sécurité temporaire avant de modifier votre processus de déploiement.

Générer une paire de clés SSH dédiée au déploiement

Pour que GitHub Actions puisse se connecter à votre VPS sans intervention manuelle, il faut utiliser une clé SSH. Cette clé permet au workflow de s’authentifier auprès du serveur sans saisir de mot de passe.

Il est fortement déconseillé de réutiliser votre clé SSH personnelle. Créer une clé SSH dédiée au déploiement limite les risques : si cette clé doit être révoquée plus tard, vous pourrez la supprimer sans impacter vos propres accès administrateur.

Dans cette étape, nous allons générer une nouvelle paire de clés, autoriser la clé publique sur le VPS, puis conserver la clé privée pour l’ajouter ensuite dans les secrets GitHub.

1. Générer la clé (depuis votre machine locale ou le VPS)

Depuis votre machine locale, ou directement depuis le VPS si vous préférez centraliser la configuration.

Lancez la commande suivante :

ssh-keygen -t ed25519 -C "github-actions-deploy" -f ~/.ssh/github_actions_deploy

Cette commande crée une paire de clés SSH avec l’algorithme ed25519, recommandé pour sa sécurité et sa légèreté. Le commentaire "github-actions-deploy" permet simplement d’identifier plus facilement l’usage de cette clé.

Lorsque le terminal demande une passphrase, appuyez deux fois sur “Entrée” pour la laisser vide. Dans un contexte classique, protéger une clé SSH par mot de passe est une bonne pratique. Mais ici, le workflow GitHub Actions doit pouvoir l’utiliser automatiquement, sans intervention humaine. Une passphrase bloquerait donc l’exécution du déploiement.

Deux fichiers sont créés :

• ~/.ssh/github_actions_deploy : la clé privée, à garder secrète ;
• ~/.ssh/github_actions_deploy.pub : la clé publique, à autoriser sur le VPS.

La clé privée ne devra jamais être ajoutée dans le dépôt Git.

2. Autoriser la clé publique sur le VPS

Une fois la clé générée, vous devez autoriser sa partie publique sur le VPS Linux. Cela permet au serveur de reconnaître la connexion initiée par GitHub Actions comme légitime.

La méthode la plus simple consiste à utiliser la commande ssh-copy-id :

ssh-copy-id -i ~/.ssh/github_actions_deploy.pub -p 22 utilisateur@IP_DU_VPS

Remplacez utilisateur par le nom de l’utilisateur SSH utilisé pour le déploiement, par exemple root ou un utilisateur dédié. Remplacez également IP_DU_VPS par l’adresse IP de votre serveur. Si votre port SSH n’est pas 22, adaptez la valeur après l’option -p.

Cette commande ajoute automatiquement le contenu de la clé publique dans le fichier ~/.ssh/authorized_keys de l’utilisateur distant.

Si ssh-copy-id n’est pas disponible sur votre système, vous pouvez copier manuellement le contenu du fichier .pub, puis l’ajouter dans ~/.ssh/authorized_keys sur le VPS. Veillez à ne copier que la clé publique, jamais la clé privée.

3. Conserver la clé privée pour l’étape suivante

La dernière étape consiste à récupérer le contenu de la clé privée SSH. C’est cette clé qui sera ajoutée dans les secrets GitHub afin que le workflow puisse se connecter au VPS pendant le déploiement.

Affichez le contenu de la clé privée avec la commande suivante :

cat ~/.ssh/github_actions_deploy

Copiez l’intégralité du résultat, y compris les lignes de début et de fin :

-----BEGIN OPENSSH PRIVATE KEY-----
...
-----END OPENSSH PRIVATE KEY-----

Cette clé privée doit être manipulée avec beaucoup de prudence. Elle donne accès au serveur pour l’utilisateur SSH configuré. Elle ne doit donc jamais être copiée dans un fichier du dépôt, envoyée par email, partagée dans un outil collaboratif ou committée, même temporairement.

Une fois la clé ajoutée dans les secrets GitHub, supprimez tout fichier temporaire qui aurait pu servir à la copier. Si vous pensez qu’elle a été exposée par erreur, révoquez-la immédiatement en supprimant la clé publique correspondante du fichier authorized_keys sur le VPS, puis générez une nouvelle paire de clés.

Configurer les secrets GitHub

Les secrets GitHub permettent de stocker des informations sensibles de manière sécurisée. Dans notre cas, ils serviront à transmettre au workflow les informations nécessaires pour se connecter au VPS LWS :

• adresse IP,
• utilisateur SSH,
• port de connexion et clé privée SSH.

L’intérêt des secrets est d’éviter d’inscrire ces données directement dans le fichier deploy.yml. Le workflow pourra les utiliser pendant son exécution, mais elles ne seront pas visibles en clair dans le dépôt.

Cette étape est essentielle pour sécuriser votre déploiement automatique avec GitHub Actions. Un fichier YAML peut être lu par toutes les personnes ayant accès au dépôt. Les identifiants, eux, doivent rester protégés.

1. Accéder aux réglages des secrets

Pour ajouter les secrets nécessaires, ouvrez le dépôt GitHub concerné, puis rendez-vous dans les paramètres du projet.

Rendez-vous dans la section : “Settings > Secrets and variables > Actions > New repository secret”.

GitHub permet de créer plusieurs types de variables. Ici, vous devez bien choisir les repository secrets, car ils seront associés uniquement à ce dépôt. C’est le bon choix pour un projet qui déploie une application précise vers un VPS précis.

Chaque secret est composé d’un nom et d’une valeur. Le nom sera utilisé dans le fichier YAML, tandis que la valeur restera masquée dans l’interface GitHub après enregistrement.

Avant de passer à la suite, préparez les informations suivantes :

• l’adresse IP du serveur,
• l’utilisateur SSH,
• le port SSH et le contenu complet de la clé privée générée précédemment.

2. Créer les secrets nécessaires

Créez maintenant les secrets utilisés par le workflow GitHub Actions. Les noms doivent être saisis avec exactitude, car ils seront appelés ensuite dans le fichier deploy.yml.

Le secret VPS_SSH_KEY doit contenir toute la clé privée, sans supprimer les lignes -----BEGIN OPENSSH PRIVATE KEY----- et -----END OPENSSH PRIVATE KEY-----. Une erreur de copie à ce niveau provoquera souvent une erreur de connexion du type Permission denied.

Une fois les secrets enregistrés, GitHub masque automatiquement leurs valeurs dans l’interface. Vous pourrez modifier ou supprimer un secret, mais vous ne pourrez pas relire sa valeur en clair. C’est un comportement normal, conçu pour protéger vos informations sensibles.

Créer le fichier de workflow

Nous avons maintenant un VPS accessible en SSH et des secrets GitHub prêts à être utilisés. Il reste à créer le fichier qui va décrire le comportement de GitHub Actions. Ce fichier s’appelle un workflow. Il indique à GitHub quand déclencher l’automatisation, sur quelle machine l’exécuter et quelles commandes lancer pour mettre à jour le site sur le serveur.

Dans notre exemple, le workflow se déclenchera à chaque push sur la branche main. Il se connectera ensuite au VPS LWS avec les secrets configurés précédemment, se placera dans le dossier du projet, récupérera la dernière version du code et relancera l’application.

1. Structure du dossier

GitHub Actions détecte automatiquement les workflows placés dans le dossier .github/workflows/ à la racine du dépôt. Si ce dossier n’existe pas encore dans votre projet, créez-le avec la commande suivante :

mkdir -p .github/workflows

La structure du dépôt doit ensuite ressembler à ceci :

mon-projet/
├── .github/
│   └── workflows/
│       └── deploy.yml
├── package.json
├── src/
└── README.md

Le nom du fichier est libre, mais il doit se terminer par l’extension .yml ou .yaml. Dans ce tutoriel, nous utiliserons deploy.yml, car son rôle est clair : gérer le déploiement automatique du projet.

Veillez à bien placer ce fichier dans .github/workflows/. S’il est créé ailleurs, GitHub ne le considérera pas comme un workflow et aucune automatisation ne sera déclenchée lors de vos prochains push.

2. Créer le fichier de déploiement

Créez maintenant le fichier .github/workflows/deploy.yml, puis ajoutez le contenu suivant :

name: Déploiement automatique VPS

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Déployer sur le VPS via SSH
        uses: appleboy/ssh-action@v1
        with:
          host: ${{ secrets.VPS_HOST }}
          username: ${{ secrets.VPS_USERNAME }}
          key: ${{ secrets.VPS_SSH_KEY }}
          port: ${{ secrets.VPS_PORT }}
          script: |
            cd /var/www/monsite
            git pull origin main
            npm ci --production
            pm2 restart monapp

Ce workflow est volontairement simple pour rester facile à comprendre.

Lorsqu’un push est effectué sur la branche main, GitHub lance un job nommé deploy. Ce job utilise une machine virtuelle Ubuntu fournie par GitHub, puis exécute une action SSH qui se connecte à votre VPS.

Les informations sensibles ne sont jamais écrites en clair dans le fichier. Elles sont appelées avec la syntaxe ${{ secrets.NOM_DU_SECRET }}. C’est cette syntaxe qui permet d’utiliser les secrets GitHub créés à l’étape précédente.

Vous devez adapter trois éléments à votre propre projet :

• le chemin /var/www/monsite, qui doit correspondre au dossier réel de votre application sur le VPS ;
• la commande npm ci --production, utile pour une application Node.js, mais à adapter pour une autre stack ;
• la commande pm2 restart monapp, qui doit correspondre au nom exact du processus géré par PM2.

Pour une application Next.js, cette logique peut servir de base afin d’automatiser le déploiement de votre application Next.js avec GitHub Actions. Pour une application PHP ou un site statique, les commandes exécutées dans script seront différentes, mais le principe reste le même : se connecter au serveur, récupérer le code, puis relancer ou rafraîchir le service nécessaire.

3. Explication ligne par ligne

Le fichier deploy.yml peut sembler technique au premier abord, mais chaque bloc a un rôle précis. Voici les principaux éléments à comprendre.

Le bloc le plus important est script, car c’est lui qui décrit réellement ce qui se passe sur le VPS. Dans notre exemple, le workflow commence par entrer dans le dossier du projet avec cd /var/www/monsite. Il récupère ensuite le dernier code disponible sur la branche main avec git pull origin main.

La commande npm ci --production installe les dépendances nécessaires en production pour une application Node.js. Elle peut être remplacée selon votre stack : composer install --no-dev pour un projet PHP, une commande de build pour un site statique, ou encore une commande Docker pour un projet conteneurisé.

Enfin, pm2 restart monapp redémarre l’application gérée par PM2. Avant d’utiliser cette ligne, vérifiez le nom exact du processus avec pm2 list ou pm2 status. Un mauvais nom de processus peut donner l’impression que le déploiement fonctionne, alors que l’application n’a pas réellement été relancée.

Ce fichier constitue une première base fonctionnelle. Vous pourrez ensuite l’améliorer avec des tests, des filtres de fichiers ou une stratégie Docker, mais il est préférable de commencer par un workflow simple et compréhensible avant d’ajouter des couches plus avancées.

Déclencher et vérifier le premier déploiement automatique

Votre fichier deploy.yml est maintenant prêt. Pour vérifier que le workflow GitHub Actions fonctionne correctement, il faut l’ajouter au dépôt, le pousser sur la branche main, puis observer son exécution depuis l’onglet Actions de GitHub.

Ce premier lancement est une étape importante. Il permet de valider à la fois la syntaxe du fichier YAML, la configuration des secrets GitHub, la connexion SSH au VPS, et les commandes exécutées côté serveur. Si une erreur apparaît, elle sera visible dans les logs du workflow.

1. Commit et push du workflow

Depuis votre machine locale, ajoutez le fichier de workflow à Git, créez un commit, puis envoyez-le sur la branche main :

git add .github/workflows/deploy.yml
git commit -m "Ajout du workflow de déploiement automatique"
git push origin main

Dès que le push est reçu par GitHub, le déclencheur défini dans le fichier deploy.yml s’active. Comme nous avons configuré :

on:
  push:
    branches: [main]

le workflow ne se lance que lorsqu’un changement est envoyé sur la branche main. Un push sur une autre branche ne déclenchera donc pas le déploiement automatique.

Après cette commande, GitHub doit normalement créer une nouvelle exécution du workflow. Si rien ne se passe, vérifiez d’abord que le fichier se trouve bien dans .github/workflows/ et que l’indentation du fichier YAML est correcte.

2. Suivre l’exécution dans l’onglet Actions

Pour suivre le déploiement, ouvrez votre dépôt GitHub, puis cliquez sur l’onglet « Actions ».

Vous devriez voir apparaître un workflow nommé « Déploiement automatique VPS », correspondant à la valeur définie dans la ligne name.

Cliquez sur l’exécution en cours pour afficher le détail du job deploy. GitHub affiche alors chaque étape du workflow, son état et sa durée. Si tout se déroule correctement, l’exécution se termine avec une coche verte.

Cette page est très utile pour confirmer que GitHub a bien déclenché le workflow après le push, que l’action SSH a pu se connecter au VPS, et que les commandes du bloc script ont été exécutées jusqu’au bout.

3. Lire les logs en cas d’échec

Si le workflow échoue, GitHub affiche une croix rouge sur l’exécution concernée. Cliquez sur le job, puis ouvrez l’étape en erreur pour lire les logs détaillés. Ces logs indiquent généralement à quel moment le déploiement s’est arrêté.

Une erreur de type Permission denied (publickey) indique souvent un problème de clé SSH : clé publique absente du fichier authorized_keys, mauvaise clé privée copiée dans le secret VPS_SSH_KEY, ou utilisateur SSH incorrect.

Une erreur liée à cd /var/www/monsite signifie généralement que le chemin du projet sur le VPS n’est pas le bon. Dans ce cas, connectez-vous manuellement au serveur en SSH et vérifiez l’emplacement exact de votre application.

Si l’erreur vient de npm ci, pm2 restart ou d’une autre commande du bloc script, le problème concerne probablement la stack applicative elle-même. Le workflow fonctionne peut-être correctement, mais la commande exécutée sur le serveur doit être adaptée à votre projet.

Les secrets GitHub peuvent apparaître sous la forme *** dans les logs. C’est normal : GitHub masque automatiquement les valeurs sensibles pour éviter leur exposition.

Superviser le déploiement côté VPS

Une fois le déploiement automatique GitHub Actions exécuté avec succès, il est important de vérifier que l’application fonctionne réellement côté serveur. Une coche verte dans l’onglet « Actions » confirme que le workflow est allé au bout, mais elle ne garantit pas toujours que le site répond correctement aux visiteurs.

La supervision côté VPS permet de contrôler l’état du processus, les logs applicatifs, la consommation de ressources et les éventuelles erreurs après redémarrage. Cette étape est particulièrement utile lors des premiers déploiements automatisés, lorsque vous ajustez encore les commandes du fichier deploy.yml.

L’objectif est simple : confirmer que le code a bien été mis à jour, que l’application a redémarré proprement, et que le serveur reste stable après le déploiement.

Avec PM2 (applications Node.js) :

Si votre application Node.js est gérée avec PM2, vous pouvez vérifier rapidement son état avec les commandes suivantes :

pm2 status
pm2 logs monapp --lines 20

La commande pm2 status affiche la liste des processus gérés par PM2, leur statut, leur consommation mémoire et leur durée d’exécution. Le processus concerné doit apparaître avec un état stable, généralement online.

La commande pm2 logs monapp --lines 20 permet de consulter les dernières lignes de logs de l’application. Remplacez monapp par le nom exact de votre processus. Cette vérification aide à repérer rapidement une erreur de démarrage, une dépendance manquante, un problème de variable d’environnement ou une exception déclenchée après la mise à jour du code.

Depuis le Panel KVM LWS :

En complément des commandes en ligne, le LWS Panel KVM permet de surveiller l’état général du VPS. Depuis la rubrique Supervision, vous pouvez suivre la charge CPU, l’utilisation de la RAM et l’activité du serveur au moment du déploiement.

Cette vue est utile pour identifier un comportement anormal après l’exécution du workflow. Par exemple, un build trop lourd peut provoquer un pic de mémoire, tandis qu’une application mal redémarrée peut générer une consommation CPU inhabituelle.

Si vous observez une hausse importante des ressources après chaque déploiement, revoyez les commandes exécutées dans le bloc script du workflow. Il peut être nécessaire d’optimiser l’installation des dépendances, de déplacer certaines étapes de build, ou de mieux encadrer le redémarrage de l’application.

Aller plus loin : variantes utiles

Le workflow présenté dans ce tutoriel constitue une base simple et efficace pour automatiser un déploiement sur VPS avec GitHub Actions. Une fois cette première version fonctionnelle, vous pouvez l’améliorer progressivement selon les besoins de votre projet.

Les variantes suivantes permettent de limiter les déclenchements inutiles, de sécuriser la mise en production avec des tests, ou d’adapter le déploiement à des projets plus complexes, notamment ceux qui utilisent Docker. L’idée n’est pas de tout ajouter dès le départ, mais de faire évoluer votre pipeline étape par étape, lorsque le besoin devient réel.

1. Restreindre le déploiement à certains fichiers modifiés

Par défaut, le workflow GitHub Actions se déclenche à chaque push sur la branche main. Cette configuration est simple, mais elle peut provoquer des déploiements inutiles. Par exemple, si vous modifiez uniquement un fichier de documentation, comme README.md, il n’est pas forcément nécessaire de relancer tout le processus de mise en production.

Pour éviter cela, vous pouvez ajouter un filtre avec paths-ignore. Il permet d’ignorer certains fichiers ou dossiers lors du déclenchement du workflow.

Voici un exemple :

on:
  push:
    branches: [main]
    paths-ignore:
      - '**.md'
      - 'docs/**'

Avec cette configuration, un push qui modifie uniquement des fichiers Markdown ou des fichiers présents dans le dossier docs/ ne déclenchera pas le déploiement automatique. En revanche, si le commit contient une modification du code applicatif, le workflow sera exécuté normalement.

Cette variante est utile pour les projets actifs, où plusieurs types de changements cohabitent : documentation, configuration, code source, scripts ou fichiers de build. Elle permet de limiter les exécutions inutiles dans l’onglet « Actions », de réduire le temps consommé par les workflows et d’éviter des redémarrages serveur sans intérêt.

Il est aussi possible d’utiliser paths au lieu de paths-ignore pour déclencher le workflow uniquement lorsque certains fichiers changent. Par exemple, vous pouvez choisir de déployer seulement si le dossier src/, le fichier package.json ou un dossier applicatif précis est modifié. Le bon choix dépend de votre organisation de projet.

2. Ajouter une étape de test avant déploiement

Un workflow GitHub Actions plus robuste ne déploie pas immédiatement le code après un push. Il commence par exécuter des tests automatisés, puis lance le déploiement sur le VPS uniquement si ces tests réussissent. Cette approche limite le risque de mettre en production une version cassée de l’application.

Voici un exemple de workflow avec deux jobs : un job test, puis un job deploy.

name: Tests puis déploiement VPS

on:
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm test

  deploy:
    needs: [test]
    runs-on: ubuntu-latest

    steps:
      - name: Déployer sur le VPS via SSH
        uses: appleboy/ssh-action@v1
        with:
          host: ${{ secrets.VPS_HOST }}
          username: ${{ secrets.VPS_USERNAME }}
          key: ${{ secrets.VPS_SSH_KEY }}
          port: ${{ secrets.VPS_PORT }}
          script: |
            cd /var/www/monsite
            git pull origin main
            npm ci --production
            pm2 restart monapp

Dans cet exemple, le job test récupère d’abord le code avec actions/checkout@v4, installe les dépendances avec npm ci, puis exécute les tests avec npm test.

La ligne importante est la suivante :

needs: [test]

Elle indique que le job deploy dépend du job test. Si les tests échouent, le déploiement ne sera pas lancé. Cette sécurité est particulièrement importante pour les projets collaboratifs, les applications avec de nombreuses dépendances ou les sites e-commerce où une erreur peut avoir un impact direct sur l’expérience utilisateur.

Vous pouvez adapter cette logique à votre stack. Pour un projet PHP, il peut s’agir de tests PHPUnit. Pour une application front-end, vous pouvez lancer un build ou des tests unitaires JavaScript. L’essentiel est de vérifier automatiquement que le code est dans un état acceptable avant de l’envoyer sur le VPS de production.

3. Déploiement via Docker plutôt que git pull direct

Le déploiement présenté jusqu’ici repose sur une logique simple : le VPS contient déjà le dépôt Git, et le workflow exécute un git pull pour récupérer la dernière version du code. Cette méthode est facile à comprendre et convient à de nombreux projets, notamment pour commencer avec GitHub Actions.

Pour des projets plus complexes, une approche avec Docker peut être plus robuste. Au lieu de mettre à jour directement le code sur le serveur, le workflow peut construire une image Docker, la publier dans un registre, puis demander au VPS de récupérer et relancer le conteneur correspondant.

Cette méthode présente plusieurs avantages. Elle permet de mieux maîtriser l’environnement d’exécution, de limiter les différences entre développement et production, et de rendre les déploiements plus reproductibles. Elle est particulièrement intéressante lorsque votre projet utilise plusieurs services, des dépendances système précises ou une configuration applicative avancée.

Dans ce cas, le workflow GitHub Actions ne se contente plus d’exécuter git pull. Il peut inclure des étapes comme :

• construire une image Docker ;
• pousser l’image vers un registre ;
• se connecter au VPS en SSH ;
• exécuter docker compose pull ;
• relancer les conteneurs avec docker compose up -d.

Cette variante dépasse le cadre de ce tutoriel, mais elle constitue une évolution naturelle si votre projet grandit. Pour approfondir cette approche, vous pouvez consulter un guide dédié afin de déployer vos applications conteneurisées avec Docker sur VPS.

Vérification du bon fonctionnement

Après la mise en place de votre déploiement automatique avec GitHub Actions, prenez le temps de vérifier chaque point important. Une automatisation fiable ne se limite pas à une première exécution réussie : elle doit être compréhensible, reproductible et facile à diagnostiquer en cas de problème.

Commencez par effectuer un petit changement dans votre projet, par exemple une modification mineure dans le code ou dans une page de test. Créez un commit, puis poussez-le sur la branche main. Le workflow doit apparaître automatiquement dans l’onglet « Actions » du dépôt GitHub.

Vérifiez ensuite les points suivants :

• un push sur la branche main déclenche bien le workflow ;
• le workflow apparaît dans l’onglet Actions avec le bon nom ;
• l’exécution se termine avec une coche verte ;
• aucune erreur de connexion SSH n’apparaît dans les logs ;
• les commandes du bloc script sont exécutées dans le bon dossier sur le VPS ;
• l’application reflète bien la dernière version du code ;
• le processus applicatif est bien redémarré, par exemple avec pm2 status ;
• les secrets GitHub ne sont jamais visibles en clair dans les logs ;
• le serveur reste stable après le déploiement, sans pic anormal de CPU ou de RAM.

Si tous ces points sont validés, votre pipeline de déploiement automatique est opérationnel. Vous pouvez maintenant pousser vos mises à jour depuis GitHub et laisser le workflow se charger des commandes répétitives sur le serveur.

Gardez toutefois une bonne habitude : surveillez les premières exécutions, surtout après une modification du fichier deploy.yml. Une petite erreur d’indentation, un mauvais chemin serveur ou une commande inadaptée peuvent bloquer le déploiement. Une fois le workflow stabilisé, il deviendra un véritable gain de temps dans votre routine de développement.

Erreurs fréquentes et cas de blocage

Même avec un workflow bien structuré, un premier déploiement GitHub Actions sur VPS peut échouer pour des raisons simples : clé mal copiée, mauvais chemin serveur, port SSH bloqué ou commande de redémarrage incorrecte. L’avantage de GitHub Actions est que chaque exécution produit des logs détaillés. Il faut donc les lire étape par étape, sans se limiter au message final d’échec.

Voici les erreurs les plus fréquentes et les solutions à vérifier en priorité.

Pour faciliter le diagnostic, commencez toujours par distinguer deux types de problèmes. Si l’erreur intervient avant l’exécution du bloc script, le souci vient probablement de la connexion SSH ou des secrets GitHub. Si l’erreur apparaît après la connexion au serveur, le problème vient plutôt des commandes exécutées sur le VPS.

Vous pouvez aussi tester manuellement chaque commande du bloc script en vous connectant au serveur en SSH. Par exemple :

cd /var/www/monsite
git pull origin main
npm ci --production
pm2 restart monapp

Si une commande échoue manuellement, elle échouera aussi dans GitHub Actions. Cette méthode permet souvent de résoudre rapidement les problèmes sans modifier inutilement le workflow.

Bonnes pratiques

Une fois le déploiement automatique opérationnel, il est important de sécuriser et de fiabiliser votre configuration. Un workflow qui fonctionne une première fois n’est pas forcément un workflow prêt pour la production à long terme. Quelques bonnes pratiques permettent de réduire les risques et d’améliorer la maintenance.

Utilisez toujours une clé SSH dédiée à l’automatisation. Cette clé ne doit servir qu’au workflow GitHub Actions. En cas de suspicion de compromission, vous pourrez la révoquer rapidement sans bloquer vos propres accès administrateur au serveur.

Évitez autant que possible d’utiliser le compte root pour le déploiement. Lorsque c’est possible, créez un utilisateur dédié avec uniquement les droits nécessaires au projet. Cette approche limite les conséquences en cas d’erreur dans le workflow ou d’exposition accidentelle d’un accès.

Ne stockez jamais d’identifiant, d’adresse IP sensible, de mot de passe ou de clé privée SSH directement dans le fichier deploy.yml. Toutes les données sensibles doivent passer par les secrets GitHub. Le fichier YAML doit rester lisible, mais jamais contenir d’informations confidentielles.

Ajoutez progressivement une étape de test avant le déploiement. Même un test simple, un lint ou une commande de build peut éviter de mettre en production une version cassée. Pour un projet professionnel, le couple tests automatisés + déploiement conditionnel devient rapidement indispensable.

Créez un snapshot LWS avant les changements importants du pipeline. C’est particulièrement utile lorsque vous modifiez le processus de build, le gestionnaire de processus, la configuration PM2, Docker ou les permissions serveur.

Surveillez régulièrement l’onglet “Actions” de GitHub. Un workflow peut échouer silencieusement si personne ne consulte les exécutions. Prenez l’habitude de vérifier les premiers déploiements après chaque modification du fichier YAML.

Enfin, documentez votre processus. Ajoutez dans le dépôt un court fichier expliquant le rôle du workflow, les secrets nécessaires, le chemin du projet sur le VPS et les commandes exécutées. Cette documentation sera précieuse si un autre développeur doit reprendre le projet.

FAQ

GitHub Actions est-il gratuit pour déployer sur un VPS personnel ?

Oui, GitHub Actions peut être utilisé pour déployer un site sur un VPS personnel. GitHub propose des minutes d’exécution incluses selon le type de compte et la visibilité du dépôt. Pour un petit projet, un workflow simple de déploiement SSH consomme généralement peu de ressources. Il faut toutefois surveiller l’usage si les workflows deviennent fréquents, longs ou complexes.

Quelle est la différence entre GitHub Actions et GitLab CI/CD ?

GitHub Actions est intégré à GitHub, tandis que GitLab CI/CD est intégré à GitLab. Les deux outils permettent d’automatiser des tests, des builds et des déploiements. Le choix dépend surtout de l’endroit où votre code est hébergé, de vos habitudes de travail et de votre besoin éventuel d’une solution auto-hébergée.

Comment sécuriser les identifiants utilisés dans un workflow GitHub Actions ?

Il faut utiliser les secrets GitHub pour stocker les informations sensibles : adresse du serveur, utilisateur SSH, port et clé privée SSH. Ces données ne doivent jamais être écrites directement dans le fichier YAML. Il est aussi recommandé d’utiliser une clé SSH dédiée au déploiement et un utilisateur serveur avec des permissions limitées.

Peut-on utiliser GitHub Actions pour déployer un site WordPress ?

Oui, il est possible d’utiliser GitHub Actions pour déployer un site WordPress, mais la méthode dépend de votre organisation. Vous pouvez automatiser le déploiement d’un thème, d’un plugin ou d’un projet versionné. En revanche, il faut faire attention aux fichiers générés par WordPress, aux médias, à la base de données et aux modifications réalisées directement depuis l’administration.

Que faire si le déploiement automatique échoue sans message d’erreur clair ?

Commencez par ouvrir l’onglet Actions, puis consultez les logs détaillés du job en erreur. Vérifiez ensuite la connexion SSH, les secrets GitHub, le chemin du projet sur le VPS et chaque commande du bloc script. Le plus efficace est souvent de se connecter manuellement au serveur et de rejouer les commandes une par une.

Faut-il un VPS pour utiliser GitHub Actions, ou existe-t-il des alternatives ?

Il n’est pas obligatoire d’avoir un VPS pour utiliser GitHub Actions. L’outil peut aussi servir à lancer des tests, construire un site statique, publier un paquet ou déployer vers d’autres plateformes. En revanche, pour déployer sur une infrastructure que vous contrôlez totalement, un VPS Linux reste une solution flexible, notamment grâce à l’accès SSH et aux droits d’administration.

Conclusion

Mettre en place un déploiement automatique avec GitHub Actions permet de gagner du temps, de réduire les erreurs humaines et de fiabiliser les mises en production. ✨En configurant un workflow YAML, une clé SSH dédiée et des secrets GitHub, vous pouvez déclencher la mise à jour de votre site à chaque push sur la branche main, sans vous connecter manuellement au serveur. Cette approche reste simple à comprendre, tout en constituant une excellente première étape vers une vraie logique CI/CD. 😊Avec un VPS KVM LWS, vous disposez d’un environnement flexible, d’un accès root, de snapshots et d’outils de supervision pour sécuriser votre pipeline. Une fois ce premier workflow stabilisé, vous pourrez l’enrichir avec des tests, des filtres de déclenchement ou un déploiement Docker.

Besoin d’un serveur VPS KVM performant et flexible ?

Découvrez nos offres VPS KVM haut de gamme : des ressources garanties et un contrôle total pour vos projets. Profitez d’un hébergement 100 % SSD, d’un accès root complet, le tout dans un datacenter en France. Démarrez dès maintenant à partir de 4,99 €/mois !

Je choisis mon VPS KVM

Vous avez une question, un retour d’expérience ou une difficulté avec GitHub Actions ? Partagez-la en commentaire : cela pourra aider d’autres lecteurs à sécuriser leur propre déploiement automatique.