Vérifier les liens cassés sur GitLab dans les wikis et la documentation Markdown

La documentation GitLab casse souvent pour des raisons très différentes d’un site marketing classique. Entre les wikis, les fichiers du dépôt, les branches de release, les monorepos et les instances privées, les liens deviennent vite fragiles si personne ne les vérifie régulièrement.

Le vrai risque n’est pas seulement le 404 externe. Ce sont aussi les liens internes qui semblent corrects visuellement, mais qui ne pointent plus vers la bonne page après un renommage de branche, un déplacement de dossier ou une refonte de la documentation.

Où les liens GitLab cassent le plus souvent

Wikis vs dépôt : les règles d’URL ne sont pas les mêmes, et les liens copiés d’un contexte à l’autre cassent facilement.
URLs liées à une branche : les liens en blob/main ou blob/master deviennent fragiles dès qu’une branche est renommée ou qu’une release vit sa propre vie.
Dossiers déplacés : les réorganisations de /docs, /handbook ou des services d’un monorepo laissent souvent des liens obsolètes dans les README.
Ancres Markdown : un simple changement de titre peut casser une table des matières ou un lien profond vers une section.
Instances privées : un scan externe peut être bloqué, incomplet, ou inadapté à une doc interne protégée.

Ce qu’un bon audit GitLab doit vraiment vérifier

Les README et docs du dépôt : pages d’installation, guides d’usage, contribution, release notes.
Les chemins relatifs : ../docs/setup.md, /docs/runbook.md, images et fichiers joints.
Les ancres : liens vers des sections qui dépendent du slug généré par GitLab.
Les liens externes : portails support, dashboards, docs fournisseurs, registres de packages.
Le contexte de branche : savoir si le lien doit être résolu sur la branche courante, la branche par défaut, ou la racine du dépôt.

Règle simple qui évite beaucoup d’erreurs

Quand le contenu est dans le même dépôt, privilégiez les liens Markdown relatifs. Ils survivent beaucoup mieux aux migrations GitLab, aux changements d’hôte et aux renommages de branche que les URLs complètes.

Meilleure option pour les projets GitLab privés

Pour les projets internes, collez directement le contenu Markdown dans l’outil Markdown. Cela évite les problèmes d’authentification, réduit les faux négatifs et vous permet de vérifier vos liens sans exposer vos URLs internes à un crawl externe.

Workflow recommandé pour une équipe GitLab

Commencer par le fichier modifié : README, doc technique, runbook ou guide de release lié à la MR.
Corriger les liens internes d’abord : ce sont eux qui bloquent le plus vite les développeurs et les ops.
Revérifier les ancres après les changements de titres : c’est une régression très fréquente dans les docs GitLab.
Tester aussi les branches de maintenance : un lien valide sur main peut être cassé dans une branche supportée en parallèle.
Planifier un audit hebdomadaire : utile pour détecter la dégradation des liens externes sur les anciennes docs.

Automatiser la vérification dans GitLab CI

Le plus simple est de contrôler les docs dans les merge requests, puis d’ajouter un audit périodique sur la branche par défaut pour surveiller les liens externes qui se dégradent avec le temps.

check_links:
  image: lycheeverse/lychee:latest
  script:
    - lychee --verbose --no-progress README.md docs/*.md
  only:
    - merge_requests

Priorités de correction

Onboarding : installation, accès, configuration locale, premiers pas.
Runbooks : dashboards, procédures d’incident, escalades, liens de supervision.
Templates partagés : README et docs copiés dans plusieurs services.
Docs de release : notes de version, migrations, upgrades et breaking changes.

Si vous voulez mettre en place ce workflow rapidement, commencez par le scanner Markdown de DeadLinkTool pour vos README et docs, puis ajoutez le contrôle CI une fois les pages les plus critiques nettoyées.