Publier Hugo sur GitLab Pages via GitLab CI

Publier Hugo sur GitLab Pages via GitLab CI Publier Hugo sur GitLab Pages via GitLab CI: tutoriel complet pour nommer le dépôt, configurer baseURL, ajouter le thème en submodule et automatiser la publication. Publier Hugo sur GitLab Pages via GitLab CI est une solution robuste pour diffuser un blog statique sans serveur.

Publier Hugo sur GitLab Pages via GitLab CI est une solution robuste pour diffuser un blog statique sans serveur. Ce guide détaille les choix techniques, les règles de nommage du dépôt et la configuration du workflow d’automatisation, afin d’obtenir une publication fiable et réutilisable.

Pourquoi combiner Hugo, GitLab Pages et CI

Hugo est un générateur de site statique rapide qui produit des fichiers HTML, CSS et JavaScript prêts à être déployés. GitLab Pages fournit l’hébergement statique, tandis que GitLab CI permet d’automatiser la construction et la publication à chaque modification. Cette approche garantit que chaque push déclenche une reconstruction du site et un déploiement sans intervention manuelle, tout en conservant un historique clair des déploiements.

Pour que le déploiement fonctionne sans accroc, deux éléments techniques comptent particulièrement : le baseURL du site Hugo et la gestion des dépendances visuelles (thème) via un submodule Git. Le baseURL doit pointer vers l’emplacement GitLab Pages correspondant, afin que les liens internes restent cohérents une fois publiés.

Éléments clés avant le déploiement

Nom du dépôt et URL Pages : si vous optez pour une page utilisateur, le nom du dépôt doit suivre la convention pseudo.gitlab.io et l’URL publique sera https://pseudo.gitlab.io. Pour un projet appartenant à un groupe, l’URL ressemblera à https://groupe.gitlab.io/nom-du-projet.

• Initialiser le site Hugo : créez le site avec hugo new site mon-site ou initiez le répertoire existant et placez le contenu dans content.
• Ajouter le thème en submodule : placez le thème sous themes/nom-du-theme et référencer-le dans le fichier de configuration de Hugo. L’utilisation du submodule permet de suivre les mises à jour du thème sans copier les fichiers à chaque mise à jour.
• Configurer baseURL : dans config.toml, définissez baseURL = "https://pseudo.gitlab.io/" (ou l’URL adaptée à votre Pages).
• Préparer le CI : activez le fetch des submodules dans le pipeline et configurez une étape de déploiement qui publie le contenu généré dans le répertoire public/.

Étapes concrètes pour déployer

Ci-dessous, un exemple minimal mais fonctionnel de déploiement, utilisable tel quel ou adapté à votre configuration. L’exemple suppose que votre dépôt est une page utilisateur et que Hugo est utilisé pour générer le site.

# .gitlab-ci.yml
image: klakegg/hugo:latest
stages:
  - build
  - deploy

variables:
  GIT_SUBMODULE_STRATEGY: recursive

build:
  stage: build
  script:
    - hugo -D
  artifacts:
    paths:
      - public
    expire_in: 1 week

deploy:
  stage: deploy
  script:
    - echo "Déploiement sur GitLab Pages terminé"
  only:
    - main

Notes importantes :

• Le paramètre GIT_SUBMODULE_STRATEGY: recursive permet de récupérer le thème en submodule lors du build.
• Le pipeline publie le contenu généré dans le dossier public/, que GitLab Pages sert ensuite comme site web.
• Adaptez l’image du conteneur et les commandes Hugo à votre version et à votre configuration locale.

Personnalisation et bonnes pratiques

Pour que l’expérience soit fluide et durable, privilégiez ces choix :

• BaseURL cohérent : assurez-vous que baseURL reflète l’URL publiquement accessible, et évitez les redirections imprévues en phase de build.
• Thème en submodule : maintenez le lien avec le thème via le fichier .gitmodules et mettez à jour régulièrement la référence du submodule pour bénéficier des correctifs et améliorations.
• URLs propres : activez les URLs relatives si vous prévoyez de migrer entre environnements (dev/test/production) pour éviter les liens cassés.
• Sécurité et accès : GitLab Pages fonctionne avec des dépôts publics ou privés selon les permissions. Veillez à ce que les clés et secrets ne soient pas exposés dans le dépôt.

Limites et ce qu’on peut encore améliorer

Cette approche est idéale pour les blogs statiques, mais elle a ses limites. Les pages générées restent statiques, ce qui exclut les dynamiques côté serveur sans configuration supplémentaire. Le temps de build peut varier selon la taille du site et le nombre de sous-modules. Enfin, la gestion des domaines personnalisés et des certificats SSL nécessite une configuration spécifique côté GitLab Pages et peut varier selon les comptes et les projets.

Pour terminer

Avec Hugo sur GitLab Pages via GitLab CI, vous obtenez une chaîne automatisée et reproductible entre création de contenu, génération des pages et publication publique. Surveillez les mises à jour du thème et du moteur Hugo, et ajustez le pipeline au fur et à mesure que votre site évolue.