
Tutoriel : Déployer un site web en SSH avec Github Actions
Dans ce tutoriel, nous allons apprendre à créer une pipeline de déploiement en utilisant les Github Actions. L’objectif est de comprendre leur fonctionnement avec un exemple concret et facile à mettre en place.
Commençons avec un peu de théorie pour mieux comprendre les Github Actions et leur fonctionnement.
Qu’est-ce que Github Actions ?
Github Actions est une plateforme dédiée à l’intégration et au déploiement continue. Elle nous permet de créer des workflows pour construire (build), tester et déployer des services web.
Les workflows sont déclenchés suite à un événement, par exemple un push sur la branche master, et sont construits avec un ou plusieurs jobs. Chaque job est une machine virtuelle indépendante qui peut être exécuté en parallèle avec d’autres jobs ou de manière séquentielle.
Une action est une application personnalisée pour la plateforme Github qui exécute une tâche fréquemment répétée. Il est possible de développer ses propres Github Actions, mais on peut aussi en retrouver sur le Github Marketplace.
Pour notre tutoriel, nous nous contenterons d’utiliser des actions présentes sur le Marketplace.
Il est important de noter que Github n’est pas le seul outil permettant de créer des workflows d’intégration continue et que, par exemple, Gitlab propose un outil similaire.
Maintenant que nous savons ce que sont les Github Actions et ce qu’elles nous permettent de faire, nous allons voir comment développer un petit workflow CI/CD qui s’occupera de build un petit projet Nuxt puis de le déployer sur un serveur Nginx (Le principe est exactement le même pour tout type de serveur).
Pre-requis
- Serveur avec des accès SSH (Par exemple, un droplet DigitalOcean)
- Un compte Github
- Un projet Web (nous utiliserons un projet Nuxt pour notre exemple)
Tutoriel : Déployer son projet avec Github actions en SSH
Pour commencer, nous allons créer le fichier dans lequel nous allons écrire notre workflow Github Actions.
À la racine de notre projet, nous allons créer un dossier .github/workflows
. Ensuite, on ajoute un fichier ci.yml
À noter : le nom du fichier n'a pas d'importance dans notre cas
Instancier un workflow Github actions
Pour commencer, nous allons ajouter la propriété on. Elle nous permet de décrire l’événement déclencheur de notre pipeline. Pour notre exemple, nous souhaitons que le workflow soit déclenché lorsque nous effectuons un push sur la branche master. Elle existe d’autres événements permettant de déclencher un workflow Github que vous pouvez retrouver dans la documentation officielle.
Nous allons aussi ajouter la propriété name qui permet simplement d’afficher un nom sur l’interface Github.
name: Project Deployement
on:
push:
branches: [master]
Ajouter un job Github
La suite de notre script va se découper en 2 parties (job). Notre premier job
sera dédié et build du projet afin de créer le bundle final. Notre second job
sera dédié au déploiement de notre bundle sur le serveur.
Nous allons donc ajouter à notre fichier notre nouveau job :
...
jobs:
build:
runs-on: ubuntu-latest
Le nom de notre job → build
n’as pas d’importance
Un job
est une machine virtuelle qui est construite à la volée afin de pouvoir lancer nos commandes et réaliser différentes actions. Il faut donc lui définir un environnement de travail, ici ubuntu-latest
. Il est possible de travailler avec d’autres environnements comme windows ou mac-os.
Build notre projet Nuxt avec Github Action
On y arrive enfin, nous allons utiliser notre première Github Action.
La première action que nous souhaitons faire, c’est récupérer notre code depuis notre dépôt Git. Github nous fournit pour cela une action actions/checkout@v2
. Celle-ci va cloner notre projet dans notre job.
On définit notre première step
avec la propriété name
et on utilise la Github Action avec uses
.
Notre seconde step
nous permettant de générer le bundle utilise la propriété run
qui nous permet de lancer une commande dans notre runner Ubuntu. Dans notre cas, nous installons les dépendances du projet avec yarn
puis nous générons notre bundle avec yarn generate
.
...
steps:
- name: Download project from git
uses: actions/checkout@v2
- name: Build project
run: |
yarn
yarn generate
À ce stade, notre projet est fonctionnel et nous allons pouvoir le tester avec Github. Youhou !!
Lancer notre premier workflow Github
Comme nous l’avons vu précédemment, nous avons défini comme événement déclencheur un push sur la branche Master. On sait donc ce qu’il nous reste à faire 😉
Une fois notre push réalisé, on peut se rendre sur la page du projet dans l’onglet Actions
et nous devrions voir apparaître quelque chose comme :
Notre premier workflow Github a démarré !!
Si la pastille jaune est rouge de votre côté, c’est qu’il y a certainement une erreur dans le script. Vérifiez bien l’indentation de votre fichier et que vous n’avez oublié aucune étape.
Note: En cliquant sur le workflow en cours, vous pouvez voir le détail de chaque ligne exécutée par le script.
Utiliser un artifact pour partager des données entre nos jobs
Maintenant que notre bundle est généré et prêt pour la production, nous allons pouvoir le déployer. Mais avant toute chose, il va falloir partager notre bundle à notre job
de déploiement. En effet, un job
est une machine virtuelle construite à la volée et ne partage donc pas ses ressources avec les autres jobs
.
C’est là qu’intervient notre deuxième Github Action : action/upload-artifact@master
.
L’artifact est comme un dossier sur le cloud où notre job build
va envoyer le bundle et où notre job deploy
le récupérera.
On créé une deuxième step toujours avec les propriétés uses
et name
. Puis, on précise avec la propriété with
le nom que l’on souhaite donner à notre artifact ainsi que le chemin du dossier que l’on souhaite sauvegarder.
---
- name: Download project as artifact
uses: actions/upload-artifact@master
with:
name: bundle
path: ./dist
Note : Le nom de l'artifact est important, car c'est la référence au dossier que nous sauvegardons.
Notre premier job
est terminé. Nous pouvons de nouveau faire un push sur master afin de tester notre script.
Une fois notre workflow terminé, notre interface Github devrait ressembler à la capture ci-dessus. On y retrouve notre fichier ci.yml
avec notre job build
qui s’est bien déroulé et en dessous, notre artifact.
Déployer notre projet en SSH avec l’action easingthemes/ssh-deploy
Pour notre deuxième job, on n’oublie pas les acquis et on reprend la même structure que le premier à une petite différence : la propriété needs
.
---
deploy:
runs-on: ubuntu-latest
needs: build
Ici, on précise que notre job a besoin du job build
pour fonctionner. deploy
sera alors lancé uniquement lorsque build
sera terminé.
Tout d’abord, on va utiliser l’action actions/download-artifact@master
afin de télécharger notre bundle dans notre runner Github. Avec with
, comme pour l’upload, on précise le nom de l’artifact ainsi que le chemin où l’on souhaite importer notre dossier.
...
steps:
- name: Download artifact
uses: actions/download-artifact@master
with:
name: bundle
path: ./dist
Enfin, notre deuxième et dernière step est pour déployer notre projet en SSH. Pour ce faire, nous allons utiliser l’action easingthemes/ssh-deploy@v2.1.4
. Pour fonctionner, cette Github Action a besoin de certains paramètres que vous pouvez retrouver dans leur documentation.
Les trois variables d’environnements SSH_PRIVATE_KEY
, REMOTE_HOST
et REMOTE_USER
sont requises et varient évidemment en fonction de votre fournisseur et de votre clé SSH générée.
La variable SOURCE
définie le chemin du dossier qui doit être envoyé sur le serveur et TARGET
son chemin sur le serveur.
...
- name: Deploy project with SSH
uses: easingthemes/ssh-deploy@v2.1.4
env:
SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
REMOTE_HOST: ${{ secrets.REMOTE_HOST }}
REMOTE_USER: ${{ secrets.REMOTE_USER }}
SOURCE: "dist"
TARGET: "~/"
Afin de définir nos variables d’environnements, il faut se rendre dans les paramètres de notre projet Github (Settings > Secrets
). On appuie ensuite sur le bouton New repository secret
et on peut ajouter nos trois variables d’environnement (SSH_PRIVATE_KEY
, REMOTE_HOST
, REMOTE_USER
)
Pour rappel :
SSH_PRIVATE_KEY
: correspond à la clé privée SSH que vous avez généré qui commence par ‘——-BEGIN OPENSSH PRIVATE KEY———’
REMOTE_HOST
: correspond à votre host, une adresse ip par exemple.
REMOTE_USER
: correspond à l’utilisateur vous permettant de vous connecter à votre serveur.
Vous n’avez plus qu’à push sur la branche master
. Et c’est partiiii !!
À la fin du build et du déploiement, vous devriez retrouver l’interface de Github Actions avec quelque chose de similaire à l’image ci-dessous. On retrouve nos deux jobs : build
et deploy
et notre artifact bundle
.
Si vous vous rendez sur votre serveur, vous devriez retrouver votre dossier /dist
.
Conclusion
Dans ce tutoriel, nous avons découvert la plateforme Github Actions qui permet de créer des workflows d’intégration. Nous avons vu comment déployer simplement un site web sur un serveur de production avec pour exemple un projet Nuxt. Le script présenté dans ce tutoriel et évidemment adaptable à d’autres Framework front et des sites web classique.
Github Actions nous offre beaucoup d’autres actions pour améliorer nos workflows en intégrant, par exemple, des tests unitaires ou des tests d’intégrations.
Vous pouvez retrouver l’intégralité du projet sur mon github.