doc-locale/fr-fr/ci/debugging.md
{{< details >}}
{{< /details >}}
GitLab propose plusieurs outils pour faciliter le débogage de votre configuration CI/CD.
Si vous ne parvenez pas à résoudre les problèmes de pipeline, vous pouvez obtenir de l'aide auprès de :
Si vous rencontrez des problèmes avec une fonctionnalité CI/CD spécifique, consultez la section de dépannage correspondante :
includesscriptUne syntaxe incorrecte peut être une source précoce de problèmes. Le pipeline affiche un badge yaml invalid et ne démarre pas si des problèmes de syntaxe ou de formatage sont détectés.
.gitlab-ci.yml avec l'éditeur de pipeline {#edit-gitlab-ciyml-with-the-pipeline-editor}L'éditeur de pipeline est l'expérience d'édition recommandée (plutôt que l'éditeur de fichier unique ou le Web IDE). Il inclut :
.gitlab-ci.yml..gitlab-ci.yml localement {#edit-gitlab-ciyml-locally}Si vous préférez modifier votre configuration de pipeline localement, vous pouvez utiliser le schéma GitLab CI/CD dans votre éditeur pour vérifier les problèmes de syntaxe de base. Tout éditeur prenant en charge Schemastore utilise le schéma GitLab CI/CD par défaut.
Si vous devez créer un lien direct vers le schéma, utilisez cette URL :
https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/assets/javascripts/editor/schema/ci.json
Pour consulter la liste complète des balises personnalisées couvertes par le schéma CI/CD, vérifiez la dernière version du schéma.
Vous pouvez utiliser l'outil CI Lint pour vérifier que la syntaxe d'un extrait de configuration CI/CD est correcte. Collez des fichiers .gitlab-ci.yml complets ou des configurations de job individuelles pour vérifier la syntaxe de base.
Lorsqu'un fichier .gitlab-ci.yml est présent dans un projet, vous pouvez également utiliser l'outil CI Lint pour simuler la création d'un pipeline complet. Il effectue une vérification plus approfondie de la syntaxe de configuration.
Utilisez workflow:name pour attribuer des noms à tous vos types de pipeline, ce qui facilite leur identification dans la liste des pipelines. Par exemple :
variables:
PIPELINE_NAME: "Default pipeline name"
workflow:
name: '$PIPELINE_NAME'
rules:
- if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
variables:
PIPELINE_NAME: "Merge request pipeline"
- if: '$CI_PIPELINE_SOURCE == "schedule" && $PIPELINE_SCHEDULE_TYPE == "hourly_deploy"'
variables:
PIPELINE_NAME: "Hourly deployment pipeline"
- if: '$CI_PIPELINE_SOURCE == "schedule"'
variables:
PIPELINE_NAME: "Other scheduled pipeline"
- if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
variables:
PIPELINE_NAME: "Default branch pipeline"
- if: '$CI_COMMIT_BRANCH =~ /^\d{1,2}\.\d{1,2}-stable$/'
variables:
PIPELINE_NAME: "Stable branch pipeline"
La vérification des variables présentes dans un pipeline et de leurs valeurs est un élément clé du dépannage CI/CD. Une grande partie de la configuration de pipeline dépend des variables, et les vérifier est l'un des moyens les plus rapides de trouver la source d'un problème.
Exportez la liste complète des variables disponibles dans chaque job problématique. Vérifiez si les variables attendues sont présentes et si leurs valeurs correspondent à ce que vous attendez.
Vous pouvez définir des variables CI/CD qui ne sont pas utilisées lors des exécutions de pipeline standard, mais qui peuvent être utilisées pour le débogage à la demande. Si vous ajoutez une variable comme dans l'exemple suivant, vous pouvez l'ajouter lors des exécutions manuelles du pipeline ou d'un job individuel pour modifier le comportement de la commande. Par exemple :
my-flaky-job:
variables:
DEBUG_VARS: ""
script:
- my-test-command $DEBUG_VARS /test-dirs
Dans cet exemple, DEBUG_VARS est vide par défaut dans les pipelines standard. Si vous devez déboguer le comportement du job, exécutez le pipeline manuellement et définissez DEBUG_VARS sur --verbose pour obtenir des informations supplémentaires.
Les problèmes liés aux dépendances constituent une autre source courante de problèmes inattendus dans les pipelines.
Pour valider que les versions correctes des dépendances sont utilisées dans les jobs, vous pouvez les afficher avant d'exécuter les commandes de script principales. Par exemple :
job:
before_script:
- node --version
- yarn --version
script:
- my-javascript-tests.sh
Bien que vous souhaitiez toujours utiliser la dernière version d'une dépendance ou d'une image, une mise à jour pourrait inclure des changements incompatibles de façon inattendue. Envisagez d'épingler les dépendances et les images clés pour éviter les changements inattendus. Par exemple :
variables:
ALPINE_VERSION: '3.18.6'
job1:
image: alpine:$ALPINE_VERSION # This will never change unexpectedly
script:
- my-test-script.sh
job2:
image: alpine:latest # This might suddenly change
script:
- my-test-script.sh
Vous devez tout de même vérifier régulièrement les mises à jour des dépendances et des images, car celles-ci peuvent contenir des correctifs de sécurité importants. Vous pouvez ensuite mettre à jour manuellement la version dans le cadre d'un processus qui vérifie que l'image ou la dépendance mise à jour fonctionne toujours avec votre pipeline.
Si vous utilisez --silent pour réduire la quantité de sortie dans un job log, cela peut rendre difficile l'identification de ce qui s'est passé dans un job. De plus, envisagez d'utiliser --verbose lorsque cela est possible, pour obtenir des détails supplémentaires.
job1:
script:
- my-test-tool --silent # If this fails, it might be impossible to identify the issue.
- my-other-test-tool --verbose # This command will likely be easier to debug.
Certains outils peuvent générer des fichiers qui ne sont nécessaires que pendant l'exécution du job, mais le contenu de ces fichiers pourrait être utilisé pour le débogage. Vous pouvez les enregistrer pour une analyse ultérieure avec artifacts :
job1:
script:
- my-tool --json-output my-output.json
artifacts:
paths:
- my-output.json
Les rapports configurés avec artifacts:reports ne sont pas disponibles en téléchargement par défaut, mais peuvent également contenir des informations utiles au débogage. Utilisez la même technique pour rendre ces rapports disponibles à l'inspection :
job1:
script:
- rspec --format RspecJunitFormatter --out rspec.xml
artifacts:
reports:
junit: rspec.xml
paths:
- rspec.xmp
[!warning] N'enregistrez pas de jetons, de mots de passe ou d'autres informations sensibles dans les artefacts, car ils pourraient être consultés par tout utilisateur ayant accès aux pipelines.
Vous pouvez utiliser un outil comme Rancher Desktop ou des alternatives similaires pour exécuter l'image de conteneur du job sur votre machine locale. Ensuite, exécutez les commandes script du job dans le conteneur et vérifiez le comportement.
Vous pouvez utiliser GitLab Duo Root Cause Analysis dans GitLab Duo Chat pour dépanner les jobs CI/CD en échec.
De nombreux problèmes de pipeline courants peuvent être résolus en analysant le comportement de la configuration rules ou only/except utilisée pour contrôler l'ajout des jobs à un pipeline. Vous ne devez pas utiliser ces deux configurations dans le même pipeline, car elles se comportent différemment. Il est difficile de prédire comment un pipeline s'exécute avec ce comportement mixte. rules est le choix privilégié pour contrôler les jobs, car only et except ne sont plus activement développés.
Si votre configuration rules ou only/except utilise des variables prédéfinies telles que CI_PIPELINE_SOURCE, CI_MERGE_REQUEST_ID, vous devez les vérifier en première étape de dépannage.
Les mots-clés rules ou only/except déterminent si un job est ajouté ou non à un pipeline. Si un pipeline s'exécute, mais qu'un job n'est pas ajouté au pipeline, cela est généralement dû à des problèmes de configuration rules ou only/except.
Si un pipeline ne semble pas s'exécuter du tout, sans message d'erreur, cela peut également être dû à la configuration rules ou only/except, ou au mot-clé workflow: rules.
Si vous convertissez de only/except vers le mot-clé rules, vous devez vérifier attentivement les détails de configuration de rules. Le comportement de only/except et de rules est différent et peut entraîner des comportements inattendus lors de la migration entre les deux.
Les clauses if courantes pour rules peuvent être très utiles pour des exemples de règles se comportant comme prévu.
Si un pipeline contient uniquement des jobs dans les étapes .pre ou .post, il ne s'exécute pas. Il doit y avoir au moins un autre job dans une étape différente.
.gitlab-ci.yml contient une marque d'ordre d'octet (BOM) {#unexpected-behavior-when-gitlab-ciyml-file-contains-a-byte-order-mark-bom}Une marque d'ordre d'octet (BOM) UTF-8 dans le fichier .gitlab-ci.yml ou dans d'autres fichiers de configuration inclus peut entraîner un comportement incorrect du pipeline. La marque d'ordre d'octet affecte l'analyse du fichier, entraînant l'ignorance de certaines configurations : des jobs peuvent être manquants et des variables peuvent avoir des valeurs incorrectes. Certains éditeurs de texte peuvent insérer un caractère BOM s'ils sont configurés pour le faire.
Si votre pipeline présente un comportement confus, vous pouvez vérifier la présence de caractères BOM à l'aide d'un outil capable de les afficher. L'éditeur de pipeline ne peut pas afficher les caractères, vous devez donc utiliser un outil externe. Consultez le ticket 354026 pour plus de détails.
changes s'exécute de façon inattendue {#a-job-with-the-changes-keyword-runs-unexpectedly}Une raison courante pour laquelle un job est ajouté à un pipeline de façon inattendue est que le mot-clé changes est toujours évalué à vrai dans certains cas. Par exemple, changes est toujours vrai dans certains types de pipeline, notamment les pipelines planifiés et les pipelines pour les tags.
Le mot-clé changes est utilisé en combinaison avec only/except ou rules. Il est recommandé de n'utiliser changes qu'avec des sections if dans une configuration rules ou only/except qui garantit que le job n'est ajouté qu'aux pipelines de branche ou aux pipelines de merge request.
Deux pipelines peuvent s'exécuter lors d'un push d'un commit vers une branche associée à une merge request ouverte. En général, un pipeline est un pipeline de merge request et l'autre est un pipeline de branche.
Cette situation est généralement causée par la configuration rules, et il existe plusieurs façons de prévenir les pipelines en double.
Avant qu'un pipeline puisse s'exécuter, GitLab évalue tous les jobs de la configuration et tente de les ajouter à tous les types de pipeline disponibles. Un pipeline ne s'exécute pas si aucun job n'y est ajouté à la fin de l'évaluation.
Si un pipeline ne s'est pas exécuté, il est probable que tous les jobs avaient des configurations rules ou only/except qui les empêchaient d'être ajoutés au pipeline.
Si le mauvais type de pipeline s'est exécuté, la configuration rules ou only/except doit être vérifiée pour s'assurer que les jobs sont ajoutés au bon type de pipeline. Par exemple, si un pipeline de merge request ne s'est pas exécuté, les jobs ont peut-être été ajoutés à un pipeline de branche à la place.
Il est également possible que votre configuration workflow: rules ait bloqué le pipeline ou autorisé le mauvais type de pipeline.
Si vous utilisez la mise en miroir pull, vous pouvez consulter l'entrée de dépannage pour les pipelines de mise en miroir pull.
Un pipeline comportant plus de jobs que les limites CI/CD définies de l'instance ne démarre pas.
Pour réduire le nombre de jobs dans un seul pipeline, vous pouvez diviser votre configuration .gitlab-ci.yml en pipelines parent-enfant plus indépendants.
Les avertissements de configuration de pipeline s'affichent lorsque vous :
Job may allow multiple pipelines to run for a single action {#job-may-allow-multiple-pipelines-to-run-for-a-single-action-warning}Lorsque vous utilisez rules avec une clause when sans clause if, plusieurs pipelines peuvent s'exécuter. Cela se produit généralement lorsque vous faites un push d'un commit vers une branche associée à une merge request ouverte.
Pour prévenir les pipelines en double, utilisez workflow: rules ou réécrivez vos règles pour contrôler quels pipelines peuvent s'exécuter.
Identity verification is required in order to run CI jobs {#error-identity-verification-is-required-in-order-to-run-ci-jobs}{{< details >}}
{{< /details >}}
Lorsque vous utilisez des runners hébergés par GitLab sur GitLab.com avec un abonnement gratuit et que vous voyez un message d'erreur indiquant Identity verification is required in order to run CI jobs, vous devez effectuer une vérification d'identité.
Cette exigence aide à prévenir l'abus des ressources de calcul gratuites. En fonction de votre score de risque, vous devrez peut-être vérifier votre adresse e-mail, votre numéro de téléphone ou ajouter un mode de paiement. Pour plus d'informations, consultez la page vérification d'identité.
Pour effectuer la validation :
Vous pouvez également :
A CI/CD pipeline must run and be successful before merge {#a-cicd-pipeline-must-run-and-be-successful-before-merge-message}Ce message s'affiche si le paramètre Les pipelines doivent réussir est activé dans le projet et qu'aucun pipeline n'a encore été exécuté avec succès. Cela s'applique également si le pipeline n'a pas encore été créé ou si vous attendez un service CI externe.
Si vous n'utilisez pas de pipelines pour votre projet, vous devez désactiver Les pipelines doivent réussir afin de pouvoir accepter les merge requests.
Checking ability to merge automatically {#checking-ability-to-merge-automatically-message}Si votre merge request est bloquée avec un message Checking ability to merge automatically qui ne disparaît pas après quelques minutes, vous pouvez essayer l'une de ces solutions de contournement :
/rebase./merge.Ce problème est résolu dans GitLab 15.5.
Checking pipeline status {#checking-pipeline-status-message}Ce message s'affiche avec une icône de statut en rotation ({{< icon name="spinner" >}}) lorsque la merge request n'a pas encore de pipeline associé au dernier commit. Cela peut être dû aux raisons suivantes :
Une fois le pipeline créé, le message se met à jour avec le statut du pipeline.
Dans certains de ces cas, le message peut rester bloqué avec l'icône en rotation sans fin si le paramètre Les pipelines doivent réussir est activé. Consultez le ticket 334281 pour plus de détails.
Project <group/project> not found or access denied {#project-groupproject-not-found-or-access-denied-message}Ce message s'affiche si la configuration est ajoutée avec include et que l'une ou l'autre des conditions suivantes est remplie :
Pour résoudre ce problème, vérifiez que :
my-group/my-project et n'inclut aucun dossier dans le dépôt.The parsed YAML is too big {#the-parsed-yaml-is-too-big-message}Ce message s'affiche lorsque la configuration YAML est trop volumineuse ou imbriquée trop profondément. Les fichiers YAML comportant un grand nombre d'inclusions et des milliers de lignes au total sont plus susceptibles d'atteindre cette limite mémoire. Par exemple, un fichier YAML de 200 ko est susceptible d'atteindre la limite mémoire par défaut.
Pour réduire la taille de la configuration, vous pouvez :
script longues ou répétées dans des scripts autonomes du projet.Sur GitLab Self-Managed, vous pouvez augmenter les limites de taille.
500 lors de la modification du fichier .gitlab-ci.yml {#500-error-when-editing-the-gitlab-ciyml-file}Une boucle de fichiers de configuration inclus peut provoquer une erreur 500 lors de la modification du fichier .gitlab-ci.yml avec l'éditeur web.
Assurez-vous que les fichiers de configuration inclus ne créent pas de boucle de références entre eux.
Failed to pull image {#failed-to-pull-image-messages}{{< history >}}
{{< /history >}}
Un runner peut retourner un message Failed to pull image lorsqu'il tente de récupérer une image de conteneur dans un job CI/CD.
Le runner s'authentifie avec un jeton de job CI/CD lors de la récupération d'une image de conteneur définie avec image depuis le registre de conteneurs d'un autre projet.
Si les paramètres du jeton de job empêchent l'accès au registre de conteneurs de l'autre projet, le runner retourne un message d'erreur.
Par exemple :
WARNING: Failed to pull image with policy "always": Error response from daemon: pull access denied for registry.example.com/path/to/project, repository does not exist or may require 'docker login': denied: requested access to the resource is denied
WARNING: Failed to pull image with policy "": image pull failed: rpc error: code = Unknown desc = failed to pull and unpack image "registry.example.com/path/to/project/image:v1.2.3": failed to resolve reference "registry.example.com/path/to/project/image:v1.2.3": pull access denied, repository does not exist or may require authorization: server message: insufficient_scope: authorization failed
Ces erreurs peuvent survenir si les deux conditions suivantes sont vraies simultanément :
Pour résoudre ce problème, ajoutez tout projet contenant des jobs CI/CD qui récupèrent des images depuis le registre de conteneurs à la liste d'autorisation des jetons de job du projet cible.
Ces erreurs peuvent également se produire lors de l'utilisation d'un jeton d'accès au projet pour accéder à des images dans un autre projet. Les jetons d'accès au projet sont limités à un seul projet et ne peuvent donc pas accéder aux images d'autres projets. Vous devez utiliser un autre type de jeton avec une portée plus large.
Failed to pull image aléatoires ou intermittentes {#random-or-intermittent-failed-to-pull-image-errors}Vous pouvez rencontrer des erreurs Failed to pull image intermittentes dans vos jobs CI/CD.
Ce problème peut survenir lorsque les utilisateurs ont des permissions différentes pour accéder aux images, combiné à la façon dont les runners mettent en cache ces images. Les utilisateurs bots sont fréquemment concernés car ils ont souvent des permissions différentes de celles des autres membres du projet.
Par exemple, les images de votre pipeline peuvent être hébergées dans un registre de conteneurs dans un projet différent. Si tous les utilisateurs peuvent accéder aux deux projets, ce n'est pas un problème. Cependant, si un utilisateur (comme un utilisateur bot) ne peut pas accéder au projet hébergeant les images, il peut obtenir des erreurs Failed to pull image.
L'erreur devient intermittente lorsque le runner récupère et met en cache avec succès l'image pour un utilisateur disposant de la permission d'accéder à l'image. Ce runner dispose maintenant de l'image et n'a pas besoin d'accéder à l'autre projet pour la récupérer. Tous les utilisateurs, y compris ceux sans accès à l'autre projet, peuvent exécuter des jobs CI/CD avec cette image. Cependant, si le runner n'a jamais récupéré et mis en cache l'image, les utilisateurs sans permission d'accéder au projet d'image obtiennent l'erreur Failed to pull image.
Pour résoudre ce problème, assurez-vous que tous les utilisateurs qui exécutent des pipelines, y compris les utilisateurs bots, peuvent accéder au projet qui héberge les images récupérées.
Something went wrong on our end ou erreur 500 lors de l'exécution d'un pipeline {#something-went-wrong-on-our-end-message-or-500-error-when-running-a-pipeline}Vous pouvez recevoir les erreurs de pipeline suivantes :
Something went wrong on our end lors d'un push ou de la création de merge requests.500 lors de l'utilisation de l'API pour déclencher un pipeline.Ces erreurs peuvent survenir si les enregistrements des ID internes ne sont plus synchronisés après l'importation d'un projet.
Pour résoudre ce problème, consultez la solution de contournement dans le ticket 352382.
config should be an array of hashes {#config-should-be-an-array-of-hashes-error-message}Vous pouvez voir une erreur similaire à la suivante lors de l'utilisation de plusieurs balises !reference dans un tableau :
This GitLab CI configuration is invalid: jobs:my_job_name:parallel:matrix config should be an array of hashes.
Bien que les mots-clés script, rules et stages prennent en charge l'utilisation de plusieurs balises de référence, les autres mots-clés attendant un tableau ne le font pas. Vous pouvez utiliser l'imbrication pour contourner cette limitation, ou utiliser des ancres YAML à la place.
jobs:<job-name> config should contain either a trigger or a needs:pipeline. {#error-jobsjob-name-config-should-contain-either-a-trigger-or-a-needspipeline}Cette erreur peut survenir lorsqu'un job dans votre .gitlab-ci.yml utilise le mot-clé needs, mais n'utilise pas les mots-clés script: ou trigger:.
Chaque job doit utiliser soit le mot-clé script, soit le mot-clé trigger. Ajoutez donc le mot-clé approprié à tout job n'en utilisant aucun.
config contains unknown keys: <key-name> {#error-config-contains-unknown-keys-key-name}Vous pouvez obtenir une erreur similaire à <keyword> config contains unknown keys: <key-name>.
Ce message d'erreur peut être causé par plusieurs problèmes :
imag (invalide) au lieu de image (valide).Par exemple :
test-job:
artifacts:
path: # This is a typo, it should be `paths`
- test
image: test # This indentation is incorrect, it should be at the same level as `script`.
script:
- echo