Déployer un site Gatsby sur GitHub Pages depuis Travis CI

J’ai récemment créé un simple site web statique pour l’un de mes projets open source et testé Gatsby avec l’un de ses thèmes de démarrage. Pour héberger les pages web, j’ai décidé de publier le site statique généré par Gatsby sur GitHub Pages, où j’héberge également le code source, afin que tout soit regroupé au même endroit.

Avec GitHub Pages, deux options s’offrent à vous pour héberger et publier le site web :

1.  une branche dédiée nommée gh-pages.

2. utiliser une autre branche, par exemple master, et placer tout le code du site web dans un répertoire docs/.

Pour mon projet, j’ai choisi cette dernière option : j’ai placé tout le code source du site web dans le répertoire docs/ de la branche master, puis je l’ai déployé sur gh-pages.

Déployer sur GitHub Pages

Gatsby génère le code du site web statique dans le répertoire public/, qu’il faut envoyer sur GitHub Pages pour qu’il soit publié. Pour envoyer le code vers le dépôt distant depuis Travis CI et gérer toutes les opérations Git, nous utilisons le module npm gh-pages.

Vous pouvez également installer le module gh-pages pour tester et déployer depuis votre environnement de développement local, mais ce n’est pas obligatoire.

Étape 1 : obtenir un jeton GitHub

Pour envoyer des modifications depuis le système d’intégration continue, Travis CI dans notre cas, vers GitHub Pages, vous devez vous authentifier. Pour cela, il est recommandé d’utiliser des jetons développeur GitHub plutôt que de fournir le nom d’utilisateur et le mot de passe de votre compte.

Dans GitHub, accédez aux paramètres de votre compte -> Developer settings -> Personal access tokens, puis créez un jeton avec les autorisations d’accès au dépôt.

Dans la configuration Travis du dépôt, ajoutez une nouvelle variable d’environnement secrète nommée GH_TOKEN et définissez sa valeur sur le jeton obtenu auprès de GitHub. Veillez à NE PAS activer le paramètre display in build logs, car le jeton doit rester secret. Sinon, d’autres personnes pourraient envoyer des modifications vers votre dépôt.

Étape 2 : configurer le script de déploiement

Modifiez le fichier package.json du projet Gatsby pour y ajouter un script d’exécution deploy qui appelle gh-pages avec deux arguments de commande importants :

1. -d public - indique le répertoire contenant les fichiers générés, qui seront envoyés sur GitHub Pages comme source du site

2. -r URL - l’URL du dépôt GitHub, qui inclut un jeton GitHub permettant d’envoyer des modifications vers la branche gh-pages, sous la forme https://$GH_TOKEN@github.com/<github username>/<github repository name>.git

Voici un exemple :

"scripts": {
  "deploy": "gatsby build --prefix-paths && gh-pages -d public -r https://$GH_TOKEN@github.com/lirantal/dockly.git"
}

Étape 3 : mettre à jour .travis.yml

La configuration .travis.yml suivante peut vous servir de référence :

language: node_js
before_script:
  - npm install -g gatsby
node_js:
  - "10"
deploy:
  provider: script
  script: cd docs/ && yarn install && yarn run deploy
  skip_cleanup: true
  on:
    branch: master

Examinons les éléments importants pour déployer le site Gatsby de Travis vers GitHub Pages :

1. before_script permet d’installer Gatsby CLI afin d’utiliser la commande gatsby dans le script d’exécution du projet pour générer le site Gatsby.

2. deploy ne s’exécute que lorsque la compilation a lieu sur la branche master ; dans ce cas, il lance le script. Le script contient les instructions nécessaires pour déployer le site Gatsby situé dans le répertoire docs/. Dans ce répertoire, il faut installer toutes les dépendances du site web et exécuter le script de déploiement défini à l’étape précédente.

En résumé

En suivant ce tutoriel, vous êtes maintenant prêt à publier votre site web et à le faire découvrir au monde entier — et à nous aussi !

Si vous utilisez CircleCI ou un autre outil, le flux de travail et les principes généraux sont presque identiques ; seules diffèrent les spécificités du fichier de déploiement et des paramètres de variables d’environnement de CircleCI. Dans l’esprit de l’open source, j’ai contribué une demande de modification de la documentation au dépôt officiel de Gatsby afin de décrire l’ensemble du processus et de faciliter la tâche des futurs utilisateurs de Gatsby !