Introduction

Il y a plus d’un an je travaillais en équipe dans le cadre du passage d’un titre professionnel d’Administrateur Système DevOps. Pour étayer nos travaux nous avions choisi, entre autre, de publier un site à l’aide du très célèbre moteur de blog statique Hugo. Nous utilisions la plateforme Gitlab CI dont je vous parlais déjà pour automatiser le déploiement du site sur Gitlab Pages. C’est une plateforme pour publier gratuitement ses sites webs statiques.

Aujourd’hui nous allons voir comment publier son blog/site fabriqué avec Hugo sur Gitlab Pages, ce qui ressemblera beaucoup au tutoriel officiel de Gitlab pour construire et déployer un site Hugo. Le présent tutoriel s’appuie sur l’article précédent concernant les premiers pas avec Hugo, moteur de blog statique, je vous invite à en prendre connaissance - excepté si vous savez déjà utiliser Hugo.

Dans un premier temps nous listerons les pré-requis à l’usage de ce tutoriel, puis nous aborderons le nommage du dépôt Gitlab lors de sa création. Après quoi nous agrémenterons ce dernier avec un site Hugo (avec une configuration minime). Et nous attaquerons l’automatisation de la compilation du site sur Gitlab CI pour finalement terminer sur la publication du blog/site.

Photo d’un Tanuki du Japon qui est l’animal mascotte de Gitlab

Photo trouvée sur Wikimedia Commons concernant le Tanuki du Japon sous Licence CC BY-SA 4.0.

Pré-requis

Ce « tutoriel » peut sembler long la première fois, mais il vaut la peine d’être accompli jusqu’au bout. Les fois d’après sont plus rapides, plus faciles et ne durent que quelques minutes seulement ! Je l’ai déjà fait en moins de 10 minutes - si je devais être une référence 🤣.

Création du dépôt et règles de nommage

Dans le principe, c’est très simple :

  • vous créez un nouveau dépôt à l’aide de « Nouveau projet/dépôt » puis « Créer un projet vide »,
  • vous renseignez les champs demandés, par exemple pour l’URL de projet on choisit son pseudo dans le menu déroulant,
  • puis il s’agit de donner un nom spécifique au dépôt et un slug correspondant.

Impression écran de la création d’un projet vide avec le « slug » façon pseudonyme.gitlab.io

Parlons du nom du dépôt (et du champ « identifiant slug » hérité de ce nom).

Imaginons que vous ayez comme pseudo blankoworld, pour ne viser personne 🤣 . À défaut dans Gitlab Pages votre accès est : blankoworld.gitlab.io. Essayez : il n’y a rien pour l’instant à cette URL.

Pour faciliter les choses et bénéfier d’une adresse URL permettant d’accéder à votre blog/site statique, je vous suggère fortement de créer un dépôt nommé blankoworld.gitlab.io (oui oui, avec le domaine dans le titre du dépôt). C’est la méthode la plus simple. Bien évidemment, changez blankoworld par votre pseudo choisi sur Gitlab.

Si au contraire vous créez un dépôt nommé veille par exemple, il sera finalement disponible à l’adresse blankoworld.gitlab.io/veille. C’est ce qui permet de bénéficier de plusieurs blog/sites statiques sans être limité par Gitlab.

Il est aussi possible d’utiliser un groupe Gitlab, en ce cas cela fonctionne avec le nom du groupe, par exemple odtre.gitlab.io pour le groupe nommé odtre.

Et si vous êtes intéressés par l’usage d’un nom de domaine en lieu et place de celui fourni par Gitlab pour votre blog/site statique généré ; je vous invite à lire la documentation Gitlab au sujet des noms de domaines personnalisés.

Impression écran de l’encart « Niveau de visibilité » pour la création d’un nouveau dépôt

Autre point important : le niveau de visibilité de votre dépôt Git. Si le dépôt est public, ça facilitera possiblement les actions pour afficher le site final au reste du monde. Nous verrons cela en détail plus tard.

Impression écran de l’encart « Configuration du Projet » pour la création d’un nouveau dépôt

Laissez « Initialiser le dépôt avec un README » coché, comme ça nous aurons déjà un dépôt Git prêt à être récupéré.

Récupération initiale du dépôt et préparation

En bref, ça pourrait faire quelque chose comme les lignes suivantes dans une invite de commande :

PSEUDO_GITLAB=VOTRE_PSEUDO # par exemple blankoworld
DEPOT=VOTRE_DEPOT          # par exemple blankoworld.gitlab.io
git clone git@gitlab.com:${PSEUDO_GITLAB}/${DEPOT}
cd "${DEPOT}"
hugo new site . --force    # le point définit le dossier courant
git submodule add https://github.com/zhaohuabing/hugo-theme-cleanwhite themes/cleanwhite
echo "theme = 'cleanwhite'" >> hugo.toml
echo "public/" >> .gitignore
sed -i "s#baseURL = \(.*\)#baseURL = 'https://${DEPOT}/'#" hugo.toml
git add . # on ajoute les fichiers au prochain commit git
git commit -m "chore: Hugo initialized" # création du prochain commit
git push

Procédons étape par étape avec des explications.

On va récupérer notre dépôt Gitlab à l’aide de la commande suivante :

git clone git@gitlab.com:blankoworld/blankoworld.gitlab.io
  • blankoworld (le premier qui apparaît) est notre pseudo sur Gitlab, mais ça peut aussi être le “groupe” Gitlab sur lequel nous avons créé le dépôt (rappelez-vous le menu déroulant qui demandait l’URL du projet),
  • blankoworld.gitlab.io est le mot clé que je vous avais demandé de fabriquer en fonction de votre pseudo/groupe pour faciliter l’accès. Je dis mot-clé car il sera repéré par Gitlab pour mettre à disposition le site contenu dans le dépôt directement à la racine de l’adresse URL blankoworld.gitlab.io.

Ensuite on se rend dans ce répertoire pour préparer un site Hugo. D’après mon tutoriel sur la fabrication initiale d’un site Hugo, en choisissant le thème CleanWhite pour Hugo, cela ressemblerait à quelque chose comme :

cd blankoworld.gitlab.io  # pour se rendre dans le répertoire qu'on vient de récupérer avec Git
hugo new site . --force   # `--force` prend en compte les fichiers existant du dépôt Git
git submodule add https://github.com/zhaohuabing/hugo-theme-cleanwhite themes/cleanwhite
echo "theme = 'cleanwhite'" >> hugo.toml

Pour éviter d’augmenter la taille du dépôt Gitlab distant, on va ignorer - seulement sous Git - les fichiers contenus dans le répertoire public/. Ce qui revient à le rajouter dans le fichier .gitignore comme ceci :

echo "public/" >> .gitignore

Nous devons également adapter l’URL du site dans la configuration afin qu’il corresponde à l’URL fournie par Gitlab Pages pour servir votre - futur - site statique. Dans le cas où vous auriez suivi mes conseils et utilisé quelque chose comme mon_pseudo.gitlab.io, alors l’URL sera https://mon_pseudo.gitlab.io/. Dans mon cas c’est https://blankoworld.gitlab.io/ .

Éditons le fichier hugo.toml pour adapter l’URL du site comme il se doit :

baseURL = 'https://blankoworld.gitlab.io/'
locale = 'en-us'
title = 'My New Hugo Project'
theme = 'cleanwhite'

Il ne reste plus qu’à enregistrer les changements dans le dépôt Git et l’envoyer sur Gitlab :

git add .                               # on ajoute les fichiers au prochain commit git
git commit -m "chore: Hugo initialized" # création du prochain commit
git push                                # on pousse le résultat sur Gitlab

À ce stade, nous avons un site Hugo - très sommaire - avec un thème et l’URL de Gitlab enregistrée dans la configuration. Ce sont les seuls besoins vitaux pour compiler et publier le site. Rédiger un article est une étape qui peut attendre.

Voyons désormais comment permettre la publication de notre travail.

Automatisation avec compilation d’Hugo

La documentation de Gitlab sur l’intégration continue parle d’un fichier .gitlab-ci.yml à fournir à la base du répertoire principal.

Ce fichier .gitlab-ci.yml - oui, oui, avec un point devant le nom du fichier - va décrire les actions à effectuer pour construire, ou plutôt compiler, votre site Hugo et le publier sur Gitlab Pages.

Créons donc le fichier .gitlab-ci.yml à la base de notre répertoire principal - dans mon cas dans le dossier blankoworld.gitlab.io - avec le contenu suivant :

 1default:
 2  image: "hugomods/hugo:exts"
 3
 4variables:
 5  GIT_SUBMODULE_STRATEGY: recursive
 6  HUGO_ENV: production
 7
 8create-pages:
 9  script:
10    - hugo
11  pages: true
12  artifacts:
13    paths:
14      - public
15  rules:
16    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

C’est une version allégée de celle trouvée sur la documentation Gitlab à propos de la publication d’un site Hugo en utilisant Gitlab CI.

Inutile d’être un as de l’écriture de fichiers .gitlab-ci.yml pour en comprendre le détail :

  • Les lignes 1 à 2 renseignent l’image Docker à utiliser pour compiler votre site. Ici nous utilisons les excellentes images Docker fournies par Hugomods. Attention cependant à trouver une image qui contient aussi l’outil Git pour récupérer le thème du site,
  • ligne 4 à 6, nous avons respectivement une variable GIT_SUBMODULE_STRATEGY pour définir la statégie de récupération Git (utile pour récupérer notre thème) et HUGO_ENV pour définir l’environnement cible pour la compilation Hugo,
  • ligne 8 à 17 sont les lignes où tout va se jouer. C’est là qu’on décrit la commande à lancer - ici c’est juste hugo. Le fait qu’on souhaite utiliser Gitlab Pages et qu’on va utiliser le contenu résultant du dossier public pour l’envoyer sur Gitlab Pages.
  • ligne 15 et 16 définissent dans quel cas exécuter cette étape nommée create-pages. En l’occurrence cela ne sera que si la branche attachée au commit est la branche par défaut dans Gitlab. Si vous m’avez suivi dès le départ, nous n’avons qu’une seule branche dans Gitlab nommée master.

Une fois le fichier dûment complété, n’oubliez pas de l’ajouter au dépôt Git et de pousser le tout sur Gitlab :

git add .gitlab-ci.yml
git commit -m "feat(CI): Add .gitlab-ci.yml file to compile Hugo"
git push

Vous devriez retrouver rapidement les détails de la compilation dans le menu Gitlab (à gauche) nommé “Compilation > Pipelines”. Les pipelines de Gitlab CI représentent une suite automatisée d’étapes justement fournies dans le fichier .gitlab-ci.yml. Donc chaque fois que vous ferez un commit sur votre dépôt et que vous poussez le résultat sur Gitlab, une pipeline s’exécutera si et seulement si le fichier .gitlab-ci.yml est présent dans votre dépôt (et qu’il soit bien bien formé comme Gitlab CI l’attend).

Impression écran du menu Gitlab pour accéder aux pipelines

Mais ne crions pas victoire trop tôt, nous avons encore quelques détails à régler.

Publication de son blog

Bien entendu, suite à notre dernier commit Git, une pipeline s’est exécutée. Elle est sûrement arrivée au bout de son exécution et le site est envoyé vers Gitlab Pages.

Impression écran du résultat d’une pipeline sous Gitlab CI

Cependant même en ayant l’URL il se pourrait que vos visiteurs n’accèdent pas au site : nous devons vérifier la « visibilité du site ». Et où cela se trouve ? Dans les paramètres de votre dépôt.

Sur Gitlab, une fois sur votre dépôt :

  • allez dans le menu latéral gauche et choisissez cette fois “Paramètres > Général”,
  • puis cliquez sur le titre “Visibilité, fonctionnalités du projet, autorisations”. Vous devriez avoir une loooooongue liste de boutons à cocher/décocher,
  • parmi eux, sous un titre “Pages”, doit se trouver un bouton activé. Et un menu déroulant pour choisir qui peut voir le site,
  • si vous souhaitez que tout le monde puisse accéder au site, choisissez “Toute personne ayant accès”,
  • ET n’oubliez pas d’aller plus bas de la page pour cliquer sur le bouton “Enregistrer les modifications”. Cas échéant vos modifications n’auront aucun effet.

Le menu “Paramètres > Général” en image :

Impression écran du menu Paramètres > Général sur Gitlab

et son petit copain l’encart “Pages” également en image :

Impression écran de l’encart « u menu Paramètres > Général sur Gitlab

C’est tout bon ! Vous devriez avoir un site accessible sur mon_depot.gitlab.io, dans mon cas c’est blankoworld.gitlab.io. Allez vérifier tout de même 😉.

Conclusion

À travers quelques étapes comme la création du dépôt, celle du site Hugo, la configuration de ce dernier, l’ajout d’un fichier .gitlab-ci.yml et finalement une configuration Gitlab, nous avons vu que quelques minutes suffisent à démarrer un nouveau blog/site statique, ce qui est très pratique !

Loin d’être un modèle de beauté, nous avons pourtant un site prêt à l’usage sur Gitlab Pages, à l’adresse blankoworld.gitlab.io. Chaque nouvelle modification enregistrée par Git (via un commit) puis poussée sur Gitlab génèrera une pipeline Gitlab CI qui publiera le site Hugo sur l’adresse fournie ci-avant.

Si d’aventures vous voudriez voir ce qui a été fait, je vous invite à lire le dépôt Gitlab utilisé pour ce tutoriel sur la publication d’un site Hugo sur Gitlab Pages.

Vous pourriez aller plus loin en ajoutant un domaine personnalisé sur votre dépôt Gitlab en lisant la documentation Gitlab. Vous allez devoir cependant apprendre comment avoir un nom de domaine et comment en modifier ce qu’on appelle la zone DNS. Mais ceci est une autre histoire que nous n’aborderons pas aujourd’hui.

Amusez-vous bien et n’hésitez pas à tester votre site Hugo en local avant de pousser le résultat sur le dépôt Gitlab 😉 .

Liens utiles

Voici les liens de l’article par ordre d’apparition :