Utiliser Jekyll avec GitLab Pages

Cet article fait partie de la série "Utiliser Jekyll avec..." où je vous explique comment utiliser le générateur de site statique Jekyll sur des hébergements de sites statiques gratuits fournit par les leaders de la forge logicielle.

GitLab, solution concurrente de GitHub et Bitbucket, vient aussi avec sa solution d'hébergement de site statique lié aux projets qu'il stocke.

Cette solution est à mi-chemin entre celles de GitHub et de Bitbucket et c'est aussi celle qui me semble la plus "propre".

GitHub proposait une solution où Jekyll est complètement intégré : ce qui est top dans notre cas puisque qu'on veut utiliser Jekyll. Par contre, on ne pourra pas changer et si de base on ne voulait pas utiliser Jekyll tout aurait été plus compliqué. On se serait retrouvé dans la même situation qu'avec la solution de Bitbucket.

Bitbucket propose le minimum syndical : un espace de stockage avec chaque repo et un serveur web qui sert les fichiers statiques. Sauf que pour remplir cet espace de stockage, il se sert du repo, il faut donc stocker uniquement les fichiers buildés de Jekyll et pas le projet en lui-même. Si on veut une solution ou le projet Jekyll est versionné et le site mis à jour automatiquement, il faut tricher et utiliser deux repo et du CI/CD compliqué.

GitLab propose quant à lui, un espace de stockage avec chaque repo et un serveur web qui sert les fichiers statiques et un job spécial (CI/CD) nommé pages dont il promet de déployer l'artéfact au bon endroit. Et c'est ça qui est excellent ! GitLab nous laisse libres du choix de l'outil, de sa configuration, de notre organisation dans le repo, etc. Il dit juste : si un job pages: existe dans un projet et qu'il a un artéfact de défini, je le prends et le déploie sur le namespace GitLab Pages correspondant.

La solution de GitLab fonctionne donc pour tous les projets et tous les générateurs de sites statiques (même celui que vous avez codé ce dimanche).

Comme nous sommes libres des étapes du build aussi tout est possible pour le stockage du site. GitHub proposait les endroits suivants et ils sont aussi utilisables pour votre site sur GitLab Pages :

Mettre vos sources sur la branche master à la racine si vous n'avez que votre site dans le repository.
Mettre vos sources sur une branche spécifique, mais si vous avez le code d'un projet dans les autres branches. (Elle doit s'appeler gh-pages sur GitHub Pages, mais vous pouvez lui donner le nom que vous souhaitez sur GitLab Pages)
Mettre vos sources sur la branche que vous souhaitez dans le dossier que vous souhaitez de votre projet. (Là encore on est limité à la branche principale et au dossier /doc sur GitHub)

Step by step

On va installer Jekyll sur une branche documentation d'un de nos projets existant. Bien-sûr la procédure est presque la même si vous souhaitez installer le site à la racine du projet ou dans un répertoire.

$ gem install jekyll

On installe Jekyll sur notre machine locale.

$ git clone git@gitlab.test.com/mindsers/projet-existant.git test
$ cd test
$ git checkout --orphan documentation 
$ rm -rf *

On récupère le projet et on initialise notre branche documentation.

--orphan indique à Git qu'il doit créer cette branche sans tenir compte de l'historique du projet. La branche repart de zéro comme s'il s'agissait d'un deuxième projet complètement différent dans le même repository.

$ jekyll new . 
$ bundle update
$ git add . && git commit -m "install Jekyll website"
$ git push origin documentation

On demande à Jekyll de nous faire la structure sur laquelle on va travailler et on pousse le tout sur GitLab.

Il nous faut maintenant dire à GitLab qui y a du CI sur ce projet. Comme notre projet n'a aucune spécificité particulière (création d'une branche de zéro) nous allons pouvoir utiliser le template par défaut de GitLab :

cliquez sur "Overview" > "Set CI project"
dans la dropdown de template sélectionnez "Jekyll"
Vous pouvez commiter en sélectionnant "documentation" dans target branch

Si vous allez dans l'onglet "Pipelines" de votre projet vous devriez maintenant voir qu'un nouveau (premier ?) pipeline a été crée et lancé par GitLab. Il contient un job de test et un job de build pour votre version actuelle du site.

Le job de build s'appelle pages et contient un artéfact (votre site buildé). C'est cet artéfact que GitLab va automatiquement déployer.

Une fois fini, si vous allez sur l'adresse du site statique que vous venez de générer vous pourrez voir le site par défaut de Jekyll avec un article de bienvenue autogénéré.

Si vous rencontrez des problèmes avec la génération des URL c'est peut-être parce que Jekyll pense être à la racine d'un nom de domaine alors qu'il est dans le dossier dédié au projet. Dans _config.yml il faut rajouter une entrée baseurl: "" avec pour valeur le endpoint de votre site. Pour un site disponible a l'adresse https://gitlab.test.io/user/projectname/ ce sera /user/projectname.

$ rm -rf _posts/*
$ vim _posts/2017-12-13-coucou-c-est-moi

À partir de là vous allez passer le plus clair de votre temps dans le dossier _posts à écrire et gérer les articles/pages de votre site. Pour mettre en production, vous devrez commiter vos modifications et pousser sur le serveur.

Pour ceux qui voudraient customiser le thème voici l'aide de la doc.