%

Hugo : publier ses pages avec la forge Codeberg Pages

Héberger et publier nos articles fait avec Hugo sur Codeberg.pages

Détails relatifs à l'article

Article publié, le
5 minutes de lecture
Cet article contient 890 mots.

Identifiant de l'article : tag:it-log.fr.eu.org,2026-10-10:/fr/web/hugo/hugo_codeberg_pages/

Source brute de l'article :
Commit version : 2187255

Cet article est aussi disponible sur le protocole Gemini :
gemini://gmi.it-log.fr.eu.org/fr/web/hugo/hugo_codeberg_pages.gmi

Description

Ou comment utiliser la fonctionnalité de pages offertes par le service Git de Codeberg…

Codeberg utilise la forge Forgejo, qui est un dérivé ’no-ia’ de l’excellent Gitea, publié sous Licence v3. Une des fonctionnalités intéressante est bien-sûr les Actions CI-CD, l’équivalent compatible de GitHub Actions, ou son pendant chez Gitlab.

Cette fonctionnalité offre ni plus ni moins la possibilité d’hébergement et publication d’articles, fait en Markdown, écrit avec Hugo (et très certainement d’autres SSG). En arrière plan est installé un “runner” (un logiciel “moteur”, un exploitant) pour accomplir les actions nécessaires.

Prérequis

Des prérequis de bases, il faut avoir :

  • un compte actif sur la forge de Codeberg, puis se connecter…
  • créer un projet et déployer un dépôt local Git vers l’espace du projet
  • créer un projet Hugo, tester localement, puis le déployer au grés des modifications nécessaires

L’étape importante est de configurer le projet, pour cela, il faut :

  • aller dans les paramètres du projet,
  • puis cliquer sur le menu “Fonctionnalités”,
  • et dans la section “Vue générale”, il faut cliquer sur la case à cocher “[ ] Activer l’intégration continue avec Forgejo Actions”.

Forgejo Actions

Un nouveau sous-menu apparaît nommé logiquement “Actions”, utile pour créer les runners… *mais pas besoin d’y toucher, trois sont déjà proposés ; de même, un bouton [ ( > ) Actions ] apparaît dans le menu du bandeau supérieur. Ce bouton là est nécessaire et permet de voir les productions des runners choisis.

Menu Actions

Le site Codeberg.page restitue deux informations intéressantes pour héberger les pages statiques dans la forge logicielle.

  • Au-travers des actions CI/CD - choix à privilégier - ou sans…

Concentrons-nous sur le fait d’utiliser les actions, qui facilitent grandement la publication.

DNS

Une étape cruciale est l’écriture correcte des enregistrements DNS !

  • le premier enregistrement à modifier est où pointe le futur site web : l’utilisation d’un CNAME. Mais attention, la norme interdit l’usage d’un CNAME pour la racine @ du nom de domaine ; il est possible de l’utiliser pour tout sous-domaine, dont le fameux www.

Dans le cas de publication des pages, pour la racine au nom de domaine, il faut soit utiliser :

  • un enregistrement ALIAS - certains logiciels sont capable de les gérer ; ce n’est pas le cas de nsd sous OpenBSD, par exemple….

  • ou à défaut, si non supporté, ce sont les enregistrements de type A, et l’équivalent IPv6 AAAA ; le site Codeberg.page donne les infos adéquates. Le seul bémol est que si le projet change les adresses IP utilisées, et que vous ratez l’information, à terme les sites ne seront plus consultables.

  • puis de rajouter des enregistrements TXT nécessaires, soit :

@   IN TXT codeberg.page.
_git-pages-forge-allowlist      IN TXT https://codeberg.org/nom-utilisateur/nom-projet.git

Certs

Ce que ne dit pas la documentation - et c’est normal - est que si vous gérez par vos soins les certificats TLS nécessaires par le biais d’une authorité de certification, telle Let’s Encrypt, il est nécessaire de modifier les enregistrements DNS CAA afin de ne plus avoir finement la main sur les futurs créations, modifications desdits certificats.

Parce que dans le processus des Actions CI, la création et mise à jour des certificats TLS est gérée et offerte par le biais de Let’s Encrypt, justement.

Ainsi la configuration DNS suivante doit être à minima mise en commentaire, voire corrigée.

@    IN CAA  0 iodef "mailto:mail@domain.tld"
@    IN CAA  0 issue "letsencrypt.org;accounturi=https://acme-v02.api.letsencrypt.org/acme/acct/numero-client"
@    IN CAA  0 issuewild

Vous avez beau être propriétaire de votre nom de domaine, c’est maintenant les services de Codeberg.page qui s’en occupe. Les laisser actifs, tels quels du fait principalement de l’utilisation de la propriété accounturi, empêchera Codeberg.page de les générer ; le résultat sera que votre site web ne pourra pas être publiable.

Hugo

L’espace de documentation de Hugo nous mâche assurément le travail en nous livrant une recette utile, fonctionnelle, sans grande retouches ni complication. Tout est fait pour simplifier le processus.

La page Deploy to Codeberg Pages de la documentation Hugo explique tout, très bien.

J’attire seulement l’attention des deux, trois modifications nécessaires à apporter à votre projet Hugo :

  • Bien fixer la valeur de la variable baseURL sur l’URL de déploiement du projet dans la forge
    • dans le contexte de l’utilisation d’un nom de domaine personnalisé, de bien faire attention à ajouter le paramètre server, tel que server: codeberg.page dans la section Deploy.
  • Modifier la valeur du répertoire cache des images.
  • Choisir un des runners proposés par la forge ; par défaut, le script fourni par Hugo utilise le runner codeberg-small.

Tous ces détails, une fois vérifiés et validés, permettent le déploiement des pages Hugo.

Voilà.

Dépannage

⇒ Lors de la phase de construction Build, cette étape s’arrête au bout de quelques secondes avec un message très enigmatique, tel que :

/var/run/act/workflow/12.sh: line 6:   422 Killed                  hugo build --gc --minify --cacheDir "/tmp/.cache/hugo"
⚙️ [runner]: exitcode '137': failure

Erreur 137 ? Mais c’est quoi, ça, encore ?!

Apparemment, votre projet demande un peu trop de ressource ; la recommandation est de basculer sur le runner codeberg-medium ou son pendant codeberg-medium-lazy, qui mettra un peu plus de temps à l’exécution mais moins de ressources CPU.

Documentation

La documentation officielle :

Enjoy-ID!
Enjoy-IT!