Article · 10 septembre 2026 · 7 min de lecture

Debug Detective : la bibliothèque fermée

Un pipeline qui refusait de démarrer. Aucun job en échec, aucun log, aucune croix rouge à côté d'une étape, parce que rien n'était jamais allé jusqu'à s'exécuter. Juste un refus à la porte, et un message d'erreur écrit pour m'en dire le moins possible.

La scène

Le montage était volontaire. La logique de pipeline ne vit pas dans le dépôt applicatif ; elle vit dans un projet de composants, une bibliothèque de petits fichiers YAML versionnés que chaque projet inclut et étend. Un correctif, tous les consommateurs, zéro copier-coller. C'est tout l'intérêt.

Puis un pipeline a cessé de démarrer. Pas d'échouer : de démarrer. Aucun graphe de jobs à consulter, aucun log à ouvrir, aucune étape à déplier. GitLab avait refusé d'assembler la configuration, et tout ce qu'il consentait à me dire était ceci :

Project `group/components-ci` not found or access denied!

Premières vérifications

J'ai fait les choses évidentes, dans l'ordre évident, et chacune est revenue propre.

• Le projet de composants existait. Je l'ai ouvert dans le navigateur.
• Le chemin était bon. Le fichier était exactement là où je l'avais écrit.
• La référence était bonne. Le tag existait et pointait où il fallait.
• Aucune faute de frappe. J'ai comparé le bloc d'include au chemin du dépôt caractère par caractère, ce genre de vérification qu'on fait deux fois sans y croire tout à fait.

Donc : le projet est là, le fichier est là, la référence est là, et GitLab dit que le projet est introuvable. Cette contradiction est l'endroit où j'ai perdu les heures suivantes.

La fausse piste

Je me suis attaqué au .gitlab-ci.yml. Évidemment. L'erreur apparaît au moment où la configuration est analysée, la configuration c'est ce fichier, donc la faute est dans ce fichier. Ce raisonnement est propre, et il est faux.

J'ai réécrit le bloc d'include de trois façons. Avec la référence entre guillemets, puis sans. Je l'ai déplacé en haut du fichier au cas où l'ordre compterait. Je l'ai passé au linter CI, qui m'a répondu que la syntaxe était bonne, ce dont j'ai conclu que le linter ne vérifiait pas assez sérieusement. Quand votre modèle du problème est faux, chaque preuve qui le contredit se fait expliquer au lieu d'être crue.

Puis j'ai attrapé le second piège, et je veux le nommer parce qu'il ressemble tellement à la réponse : la liste d'autorisation du jeton de job. J'en avais lu la documentation, ça parle d'un projet qui accède à un autre, ça se règle dans les paramètres CI/CD, et ajouter mon projet à cette liste ressemblait exactement au correctif. Ça n'a rien fait, parce que le jeton de job gouverne ce qu'un job en cours d'exécution peut appeler. Mon problème survenait avant qu'aucun job n'existe.

L'indice

La rupture est venue d'une lecture attentive du message d'erreur, au lieu de le survoler. Not found or access denied. Deux possibilités, reliées par un ou, et je n'avais enquêté que sur la première.

Cette ambiguïté est volontaire. Si GitLab vous disait qu'un projet privé existe mais que vous ne pouvez pas le lire, il confirmerait l'existence de projets privés à quiconque saurait deviner un chemin. Il fond donc les deux cas dans un seul message. C'est une décision de sécurité défendable, et c'est aussi la raison pour laquelle on prend si facilement la mauvaise branche : elle vous tend une phrase où le mot introuvable occupe toute la place, et enterre discrètement la moitié qui compte.

La révélation

Un include: project: n'est pas résolu par le pipeline. Il est résolu au nom de l'utilisateur qui a déclenché le pipeline.

GitLab lit la configuration pour le compte de cette personne, et applique ses permissions sur l'autre projet. Pour un projet privé, l'utilisateur déclencheur doit avoir au moins le rôle Reporter dessus. Pour un projet interne, n'importe quel utilisateur authentifié non externe suffit. Pour un projet public, rien n'est requis.

Ma bibliothèque de composants n'était pas lisible par le compte qui lançait ce pipeline. Le fichier était exactement là où je le disais ; le pipeline n'avait simplement pas le droit de le savoir. Toutes mes vérifications, je les avais faites en tant que moi-même, dans un navigateur où j'avais l'accès. Je confirmais, encore et encore, que moi je voyais le fichier, alors que la question n'a jamais porté sur moi.

Le détail qui aurait résolu l'affaire en cinq minutes

Comme le contrôle est par utilisateur, cette panne n'est pas homogène dans une équipe. Le même pipeline, le même commit, la même configuration, passe au vert quand une personne le lance et au rouge quand une autre le lance. Si vous entendez un jour « ça marche quand je le déclenche et ça casse quand c'est lui », arrêtez de regarder le YAML. Ce symptôme n'appartient pas à un fichier. Les fichiers ne changent pas selon qui les lit ; les permissions, si.

Je n'avais pas cet indice à l'époque parce que je travaillais seul. C'est la première chose que je demanderais aujourd'hui.

Le correctif, et ce qu'il coûte

Il y a deux réponses honnêtes, et le choix dépend de ce à quoi sert la bibliothèque.

• Donner l'accès. Ajouter l'utilisateur, ou mieux un groupe, en Reporter sur le projet de composants. Correct quand la bibliothèque contient quoi que ce soit qui doive rester privé. Le coût : vous maintenez désormais une liste d'appartenance, et chaque nouvelle personne ou nouveau projet est une demande de permission en attente.
• Changer la visibilité. Passer le projet de composants en interne, ou en public. Correct quand la bibliothèque est délibérément générique, ce qui est le cas de la mienne : elle contient des jobs de build, de scan, de déploiement, de health check, de rollback et de sauvegarde, et rien là-dedans n'est un secret. Les secrets vivent dans des variables, pas dans le YAML qui les référence.

J'ai choisi la visibilité. Non pour éviter le travail d'appartenance, mais parce que devoir répondre à la question était utile : si une bibliothèque partagée a besoin que son contenu reste secret, le secret est au mauvais endroit. La rendre publique a transformé un problème de permissions en une vérification de conception, qu'elle a passée.

Note du détective

• Lisez l'erreur en entier, y compris le mot « ou ». Les messages ambigus le sont souvent exprès, et la moitié que vous sautez est celle qui vous coûte l'après-midi.
• Vérifiez qui demande, pas seulement ce qui est demandé. « Le fichier existe » et « cette identité peut lire le fichier » sont deux affirmations différentes. J'ai vérifié la première quatre fois et jamais testé la seconde.
• Ne vérifiez pas une permission en vous connectant en tant que vous. Toutes mes vérifications se sont faites dans un navigateur où j'avais déjà l'accès. Ce n'est pas un test, c'est une réassurance.
• Sachez à quelle couche appartient un réglage. La liste d'autorisation du jeton de job contrôle les appels d'API à l'exécution. La résolution des includes a lieu avant l'exécution. Deux fonctionnalités au nom identique, dans deux phases du même système.
• « Ça marche chez moi et pas chez eux » est un symptôme de permissions. Presque jamais un symptôme de fichier.