Aller au contenu

Configurer le domaine GitLab Pages

Vous êtes mainteneur·se de Kirexo et la documentation publique doit être accessible sur https://doc.kirexo.app/ plutôt que sur l'URL GitLab Pages par défaut. Cette recette explique la configuration manuelle à faire une seule fois : association du domaine, propagation DNS, certificat Let's Encrypt.

Prérequis

  • Vous avez les droits Maintainer ou Owner sur le projet GitLab.
  • Vous avez accès à la zone DNS de kirexo.app (registrar ou panneau de gestion DNS).
  • Au moins une release a déjà été créée (cf. Créer un tag de release) — sinon le job pages n'a jamais tourné et il n'y a aucun site à servir.

Pourquoi cette étape n'est pas automatisée

Le job pages publie le site, mais l'association du domaine custom vit dans les paramètres GitLab du projet et ne peut pas être déclarée côté CI. Idem pour le certificat Let's Encrypt — il est provisionné par GitLab côté serveur après vérification DNS, indépendamment des pipelines. C'est une configuration one-shot par projet.

Étape 1 — Déclarer le domaine dans GitLab

  1. Aller dans Settings → Pages.
  2. Cliquer sur New domain.
  3. Renseigner doc.kirexo.app.
  4. Cocher Automatic certificate management using Let's Encrypt.
  5. Valider.

GitLab affiche alors deux informations à reporter dans la zone DNS :

  • un enregistrement TXT de vérification (proof of ownership), du type _gitlab-pages-verification-code.doc.kirexo.app ;
  • un enregistrement CNAME ciblant le sous-domaine GitLab Pages du namespace (typiquement shaurifr.gitlab.io).

Notez les deux valeurs — l'écran ne les ré-affichera pas après que vous l'aurez fermé (vous pouvez toujours revenir dans Settings → Pages → Edit domain).

Étape 2 — Configurer la zone DNS de kirexo.app

Dans le panneau DNS de votre registrar (OVH, Gandi, Cloudflare…), créez deux entrées :

Type Nom Valeur
CNAME doc shaurifr.gitlab.io. (le point final est important)
TXT _gitlab-pages-verification-code.doc (la valeur fournie par GitLab à l'étape précédente)

Cloudflare : pas de proxy

Si la zone est gérée par Cloudflare, mettre l'enregistrement CNAME en mode DNS only (nuage gris) et pas en Proxied (nuage orange). Le proxy Cloudflare casse la négociation Let's Encrypt côté GitLab (challenge HTTP-01 reçu par Cloudflare et pas par les serveurs Pages).

La propagation DNS prend généralement quelques minutes mais peut aller jusqu'à 24 h selon le TTL.

Étape 3 — Vérification côté GitLab

De retour dans Settings → Pages → doc.kirexo.app, cliquez sur Verify ownership. Si le TXT est bien propagé, GitLab valide le domaine et bascule l'état sur Verified.

Une fois vérifié, GitLab lance automatiquement la demande de certificat Let's Encrypt. Le certificat apparaît actif (cadenas vert dans l'UI) au bout de quelques minutes. Si la demande échoue, le bouton Retry redémarre le challenge — utile quand on a corrigé une typo dans le CNAME entre-temps.

Étape 4 — Activer Force HTTPS

Toujours dans Settings → Pages :

  1. Cocher Force HTTPS (requires valid certificate).

Effet : toute requête HTTP est redirigée en HTTPS. À ne cocher qu'après que le certificat Let's Encrypt est actif — sinon les utilisateurs sont coincés sur une redirection HTTP→HTTPS qui échoue côté navigateur.

Étape 5 — Tester

curl -I https://doc.kirexo.app/

Attendu :

  • Statut HTTP/2 200 (la page d'accueil mkdocs).
  • En-tête server: nginx (les serveurs Pages tournent sur nginx).
  • Certificat valide pour doc.kirexo.app — curl -v affiche subject: CN=doc.kirexo.app et issuer: …Let's Encrypt….

Si vous obtenez un 404, c'est que le site Pages n'a pas encore été publié — créez une release (cf. Créer un tag de release) pour que le job pages tourne au moins une fois.

Maintenance ultérieure

  • Renouvellement du certificat : automatique. Let's Encrypt expire au bout de 90 jours ; GitLab renouvelle 30 jours avant l'expiration. Aucune action manuelle attendue, sauf si la propriété du domaine est invalidée (TXT supprimé).
  • Changement de namespace GitLab : un transfert du projet vers un autre namespace casse le CNAME (le sous-domaine cible change). Mettre à jour la zone DNS et révérifier le domaine.
  • Désactivation temporaire : supprimer le domaine custom dans Settings → Pages bascule l'URL canonique sur l'URL GitLab par défaut. Le DNS continue de pointer dans le vide tant que le CNAME n'est pas retiré côté registrar.

Voir aussi