05 - Troubleshooting : les erreurs qu'on a vraiment eues

Ce que tu vas apprendre

• Les 6 erreurs qu'on a rencontrees en vrai
• Le message d'erreur exact, le diagnostic, et le correctif
• Comment lire les logs d'un pipeline GitLab CI

Prerequisites

• 03 - Écrire le .gitlab-ci.yml : le pipeline est écrit
• Avoir un pipeline qui echoue (sinon, tant mieux pour toi)

---

Comment lire les erreurs de pipeline

Avant de plonger dans les erreurs spécifiques : quand un pipeline echoue, va dans CI/CD > Pipelines, clique sur le pipeline en erreur, puis sur le job rouge. Tu arrives sur les logs du job. Le message d'erreur est en général vers la fin, en rouge. Parfois il est explicite. Parfois il dit juste "exit status 1" et il faut remonter dans les logs pour comprendre.

Voici toutes les erreurs qu'on a eues en mettant en place le déploiement automatique sur paltemps.fr, dans l'ordre chronologique ou elles sont apparues.

1. "prepare environment: exit status 1"

Le message complet dans les logs du job :

ERROR: Job failed (system failure): prepare environment: exit status 1.
Check https://docs.gitlab.com/runner/shells/index.html#shell-profile-loading

Diagnostic : quand le shell executor démarré un job, il essaie de sourcer le profil bash de l'utilisateur gitlab-runner. Si .bash_logout ou .bashrc n'existent pas ou contiennent une erreur de syntaxe, le "prepare environment" echoue avant meme d'exécuter ton script.

Correctif :

bashsudo -u gitlab-runner bash -c 'touch ~/.bash_logout'
sudo -u gitlab-runner bash -c 'cp /etc/skel/.bashrc ~/. 2>/dev/null || touch ~/.bashrc'
sudo -u gitlab-runner bash -c 'touch ~/.profile'

C'est l'erreur la plus frustrante parce que le message ne dit absolument pas quel fichier manque. La page de doc linkee dans l'erreur explique le mecanisme de chargement du profil, mais il faut la lire attentivement pour comprendre.

2. "fatal: detected dubious ownership"

fatal: detected dubious ownership in repository at '/home/deploy/paltemps'
To add an exception for this directory, call:
    git config --global --add safe.directory /home/deploy/paltemps

Diagnostic : Git refuse de travailler dans un répertoire qui appartient a un autre utilisateur. Le repo a ete clone par l'utilisateur deploy (ou root), mais le runner exécuté les commandes en tant que gitlab-runner. Git considéré ca comme suspect depuis la version 2.36.

Correctif :

bashsudo -u gitlab-runner git config --global safe.directory '*'

Le wildcard '*' autorise tous les répertoires. C'est moins restrictif que de spécifier un chemin precis, mais pour un runner de déploiement sur un VPS perso, c'est largement acceptable. Si tu es dans un environnement plus sensible, mets le chemin exact.

3. "Host key vérification failed"

ssh: Could not resolve hostname gitlab.com: Temporary failure in name resolution

Ou plus souvent :

Host key verification failed.
fatal: Could not read from remote repository.

Diagnostic : le git pull se fait via SSH. L'utilisateur gitlab-runner n'a jamais contacte gitlab.com en SSH, donc le host n'est pas dans son known_hosts. SSH refuse la connexion par sécurité.

Correctif :

bashsudo -u gitlab-runner bash -c 'mkdir -p ~/.ssh && ssh-keyscan gitlab.com >> ~/.ssh/known_hosts 2>/dev/null'

Et si tu n'as pas encore de clé SSH pour le runner :

bashsudo -u gitlab-runner ssh-keygen -t ed25519 -C "gitlab-runner@vps" -f /home/gitlab-runner/.ssh/id_ed25519 -N ""

Puis ajoute la clé publique comme deploy key dans GitLab (Settings > Repository > Deploy keys).

4. "Permission denied" sur Docker

permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock

Diagnostic : l'utilisateur gitlab-runner n'est pas dans le groupe docker. Par défaut, seul root et les membres du groupe docker peuvent communiquer avec le daemon Docker.

Correctif :

bashsudo usermod -aG docker gitlab-runner
sudo gitlab-runner restart

Le restart du runner est nécessaire. Un simple restart du service suffit, pas besoin de re-register. Tu peux tester avec :

bashsudo -u gitlab-runner docker ps

5. Le CSS ne se met pas à jour

Pas de message d'erreur. Le pipeline est vert. Mais le site affiche l'ancien CSS.

Diagnostic : le cache Docker. Docker a décidé que le layer COPY . . n'avait pas change (ou que le layer de build pouvait etre réutilisé). Le build n'a pas vraiment rebuilde les assets.

Correctif :

bashdocker compose build --no-cache

Dans le .gitlab-ci.yml, remplace docker compose build par docker compose build --no-cache. On perd quelques secondes de cache, on gagne la certitude que les fichiers sont à jour. J'en parle en détail dans l'article précédent sur le cache Docker.

Si tu veux garder le cache la plupart du temps, une alternative : passer un build arg avec le hash du commit pour forcer l'invalidation :

yamlscript:
  - docker compose build --build-arg COMMIT_SHA=$CI_COMMIT_SHA

Avec dans le Dockerfile :

dockerfileARG COMMIT_SHA
COPY . .

Le ARG qui change a chaque commit invalide le cache à partir de cette instruction.

6. Le dépôt apt ne supporte pas Ubuntu 25.04

E: The repository 'https://packages.gitlab.com/runner/gitlab-runner/ubuntu plucky InRelease' does not have a Release file.

Diagnostic : les dépôts apt de GitLab Runner ne supportent pas encore Ubuntu 25.04 (plucky). Le dépôt existe pour jammy (22.04), noble (24.04), mais pas plucky.

Correctif : installer le binaire directement.

bashsudo curl -L --output /usr/local/bin/gitlab-runner \
  "https://s3.dualstack.us-east-1.amazonaws.com/gitlab-runner-downloads/latest/binaries/gitlab-runner-linux-amd64"
sudo chmod +x /usr/local/bin/gitlab-runner

C'est la méthode recommandee par GitLab pour les distributions non supportees. Le binaire est le meme que celui installe par apt, juste sans la gestion de paquets. Les mises à jour se font en retelechargeant le binaire.

En résumé

Erreur	Cause	Fix rapide
prepare environment: exit status 1	Fichiers profil manquants	touch ~/.bash_logout ~/.bashrc
dubious ownership	Proprietaire repo != runner	git config safe.directory '*'
Host key vérification failed	gitlab.com pas dans known_hosts	ssh-keyscan gitlab.com
Permission denied (Docker)	Pas dans le groupe docker	usermod -aG docker
CSS obsolète	Cache Docker	--no-cache
apt repo not found	Ubuntu 25.04 pas supporte	Binaire direct depuis S3

Si tu rencontres une erreur qui n'est pas dans cette liste, le premier reflexe c'est de lire les logs du job dans GitLab. Le deuxieme, c'est d'exécuter la commande manuellement en tant que gitlab-runner sur le VPS :

bashsudo -u gitlab-runner bash -c 'la-commande-qui-echoue'

Ca te donnera un message d'erreur plus complet que ce qui apparaît dans les logs du pipeline.

---

Navigation : Precedent : 04 - Docker cache et rebuild | Suivant : 06 - Glossaire | Retour a l'introduction

---

Sources

• GitLab Runner troubleshooting par GitLab Docs
• Shell profile loading in GitLab Runner par GitLab Docs
• Git safe.directory par Git Documentation
• Install GitLab Runner manually par GitLab Docs

Retrouve d'autres articles techniques sur paltemps.fr.