Surveillance et alertes pratiques pour GitLab CI/CD

Introduction

Quand un pipeline échoue à 3 h du matin, la différence entre une récupération de 10 minutes et une lutte de trois heures dépend souvent de ce que vous pouvez observer avant de modifier quoi que ce soit. GitLab CI/CD offre des capacités natives de surveillance, de métriques et d'alertes, mais de nombreuses équipes n'en exploitent qu'une infime partie. Elles voient un pipeline rouge, relancent le job et espèrent que tout ira bien. Ce n'est pas de la surveillance ; c'est deviner.

Cet article présente une approche pratique, axée sur les commandes, pour la surveillance et les alertes GitLab CI/CD. Il s'adresse aux développeurs, aux ingénieurs de plateforme et aux équipes techniques de startups qui doivent passer d'un problème observé à un résultat vérifié. Vous trouverez des commandes concrètes, des sorties attendues et des signaux d'échec pour les domaines clés : inventaire de la version et de l'environnement, configuration sécurisée, vérification et diagnostic, modes de défaillance et récupération, ainsi qu'une liste de contrôle opérationnelle. Chaque section comprend un exemple réel avec des espaces réservés que vous pouvez adapter à votre propre environnement.

L'objectif est la sécurité opérationnelle : observer avant de modifier, limiter le rayon d'impact, utiliser des espaces réservés plutôt que des secrets, vérifier le résultat et documenter comment récupérer si l'état attendu n'est pas atteint.

Inventaire de la version et de l'environnement

Avant de pouvoir surveiller quoi que ce soit, vous devez savoir exactement ce que vous exécutez et comment c'est déployé. Cette section explique comment inventorier votre installation GitLab, vos runners et votre environnement de manière lecture seule et réversible.

Identifier la version installée et la topologie

Commencez par déterminer la version de GitLab et le type de déploiement (auto-hébergé ou GitLab.com). Utilisez l'API GitLab ou la console Rails pour les instances auto-hébergées.

Commande en lecture seule (API) :

curl --header "PRIVATE-TOKEN: <votre_jeton_d_accès>" "https://gitlab.example.com/api/v4/version"

Sortie attendue :

{
  "version": "17.5.2",
  "revision": "c7a5f3b"
}

Signal d'échec : Si vous obtenez une erreur 401, votre jeton n'a pas la portée read_api. Si vous obtenez un refus de connexion, le service GitLab n'est peut-être pas en cours d'exécution sur cet hôte.

Pour les instances auto-hébergées, vous pouvez également vérifier la version localement :

sudo gitlab-rake gitlab:env:info

Extrait de sortie attendue :

GitLab information
Version:        17.5.2
Directory:      /opt/gitlab
DB Adapter:     PostgreSQL

Inventorier les runners et leur statut

Les runners exécutent les jobs CI. Vous devez savoir quels runners sont disponibles et s'ils sont en ligne.

Commande :

curl --header "PRIVATE-TOKEN: <votre_jeton_d_accès>" "https://gitlab.example.com/api/v4/runners/all?per_page=50"

Sortie attendue (tronquée) :

[
  {
    "id": 42,
    "description": "docker-shared-runner-1",
    "active": true,
    "online": true,
    "status": "online"
  },
  {
    "id": 43,
    "description": "kubernetes-runner-prod",
    "active": true,
    "online": false,
    "status": "offline"
  }
]

Signal d'échec : Un runner avec online: false signifie que les jobs qui lui sont assignés resteront en attente (pending). Enquêtez sur la machine du runner ou le pod Kubernetes.

Rayon d'impact et récupération pour l'inventaire

Les commandes d'inventaire sont en lecture seule et sûres. Le rayon d'impact est nul. Cependant, n'utilisez jamais de jetons avec des privilèges d'écriture pour l'inventaire. Utilisez un jeton dédié en lecture seule, ou un jeton d'accès de projet avec la portée read_api pour les appels API.

Récupération : Si vous exécutez accidentellement une commande d'écriture, annulez immédiatement les modifications et révoquez les jetons s'ils ont été exposés.

Chemin de configuration sûr

Les modifications de configuration affectent la visibilité de la surveillance. Cette section montre comment activer les métriques Prometheus, configurer les alertes et ajuster les paramètres sans casser votre pipeline.

Activer les métriques Prometheus sur GitLab

GitLab auto-hébergé peut exposer des métriques Prometheus s'il est configuré. Par défaut, le Prometheus intégré est activé, mais vous devrez peut-être activer l'exportateur pour GitLab lui-même.

Vérifier le paramètre actuel (lecture seule) :

sudo gitlab-rails runner "puts Gitlab::CurrentSettings.current_application_settings.prometheus_metrics_enabled"

Sortie attendue :

true

S'il renvoie false, vous pouvez l'activer via l'interface d'administration sous Paramètres > Métriques et profilage, ou via la console Rails (avec prudence). Le plus petit changement justifié est de basculer le paramètre dans l'interface ; une modification via la console Rails est plus risquée.

Vérification avant/après :

curl http://localhost:9090/metrics | head -n 20

La sortie attendue contient :

# HELP gitlab_ci_pipeline_size_avg Average pipeline size
# TYPE gitlab_ci_pipeline_size_avg gauge

Configurer les alertes externes

GitLab peut envoyer des alertes vers des webhooks ou des intégrations. Un modèle courant consiste à configurer un webhook pour envoyer les événements d'échec de pipeline à un outil de messagerie ou à un système de gestion d'incidents.

Exemple : webhook de projet pour les événements de pipeline.

1. Allez dans Paramètres > Webhooks de votre projet.
2. Ajoutez l'URL et sélectionnez « Événements de pipeline ».
3. Définissez un jeton secret.

Vérifiez avec un événement de test :

# Dans les paramètres du webhook, cliquez sur « Test » et sélectionnez « Événements de pipeline »

Signal attendu : Votre récepteur reçoit un payload JSON avec object_kind: pipeline et object_attributes.status égal à failed ou success.

Rayon d'impact et récupération

Une modification de configuration de webhook n'affecte que ce projet. Pour revenir en arrière, supprimez le webhook. Si vous déclenchez accidentellement un événement de test qui alerte quelqu'un, reconnaissez la fausse alarme dans votre canal d'incidents.

Vérification et diagnostic

Une fois la surveillance en place, vous devez vérifier qu'elle fonctionne et diagnostiquer les problèmes quand ce n'est pas le cas. Cette section fournit des commandes pour vérifier l'état des pipelines, inspecter les journaux de jobs et interroger les métriques.

Vérifier l'état du pipeline

Utilisez l'API GitLab pour lister les pipelines récents et leurs statuts.

Commande :

curl --header "PRIVATE-TOKEN: <votre_jeton_d'accès>" "https://gitlab.example.com/api/v4/projects/123/pipelines?per_page=5"

Sortie attendue :

[
  {
    "id": 98765,
    "status": "failed",
    "ref": "main",
    "sha": "a1b2c3d4...",
    "created_at": "2025-03-15T10:20:30Z"
  },
  {
    "id": 98764,
    "status": "success",
    "ref": "main",
    "sha": "e5f6a7b8..."
  }
]

Signal d'échec : Un pipeline avec le statut failed nécessite un diagnostic immédiat. Vérifiez le journal du job en échec.

Inspecter les journaux de jobs

Commande :

curl --header "PRIVATE-TOKEN: <votre_jeton_d'accès>" "https://gitlab.example.com/api/v4/projects/123/jobs/456/trace"

Sortie attendue : Texte brut du journal du job. Recherchez des motifs d'erreur tels que ERROR, fatal ou un code de sortie non nul.

Commande de diagnostic pour les erreurs côté runner :

sudo gitlab-runner status

Sortie attendue :

gitlab-runner: Service is running

Si le runner est arrêté, démarrez-le et vérifiez ses journaux dans /var/log/gitlab-runner/.

Interroger les métriques Prometheus

Si vous avez Prometheus qui collecte GitLab, utilisez PromQL pour diagnostiquer des métriques spécifiques à la CI.

Exemple : tendance de la durée des pipelines.

avg_over_time(gitlab_ci_pipeline_duration_seconds[1h])

Sortie attendue : Un graphique montrant la durée moyenne des pipelines sur la dernière heure. Un pic peut indiquer des problèmes d'infrastructure.

Exemple : disponibilité des runners.

gitlab_runner_autoscaling_machine_states{state="available"}

Si cette métrique tombe à zéro, votre groupe d'autoscaling n'a peut-être plus de capacité.

Modes de défaillance et récupération

Les pipelines échouent pour de nombreuses raisons. Cette section couvre les modes de défaillance courants, comment les détecter et les étapes de récupération.

Mode de défaillance : Runner hors ligne

Observation : Les jobs restent en pending pendant une période prolongée.

Commande :

curl --header "PRIVATE-TOKEN: <votre_jeton_d'accès>" "https://gitlab.example.com/api/v4/projects/123/jobs?scope=pending"

Sortie attendue : Une liste de jobs avec le statut pending. Aucun job en cours d'exécution.

Diagnostic : Vérifiez le statut du runner avec gitlab-runner status ou les journaux du pod Kubernetes.

Récupération : Redémarrez le service du runner ou augmentez le nombre de pods. Pour les runners Kubernetes, vérifiez kubectl get pods -n gitlab-runner et redémarrez le pod du runner si nécessaire.

Mode de défaillance : Échec du pipeline dû à une variable d'environnement manquante

Observation : Le job échoue avec command not found ou une erreur de variable manquante.

Commande :

# Dans le journal du job, recherchez "missing" ou "undefined"
curl --header "PRIVATE-TOKEN: <votre_jeton_d'accès>" "https://gitlab.example.com/api/v4/projects/123/jobs/456/trace" | grep -i "missing\|undefined"

Sortie attendue : Une ligne comme undefined variable: DEPLOY_TOKEN.

Récupération : Ajoutez la variable dans les paramètres CI/CD du projet (Paramètres > CI/CD > Variables) avec la portée et la protection appropriées.

Vérification : Relancez le pipeline et confirmez que le job passe.

Mode de défaillance : Espace disque plein sur le runner

Observation : Les jobs échouent avec No space left on device dans le journal.

Diagnostic : Connectez-vous en SSH au runner et exécutez df -h.

Récupération : Nettoyez le cache Docker (docker system prune -f) ou augmentez la taille du disque. Pour les runners Kubernetes, vérifiez la capacité du PVC.

Vérification : Relancez un job léger pour confirmer que le runner peut s'exécuter.

Pièges courants et comment les éviter

Piège 1 : Utiliser des secrets partagés dans les scripts de surveillance

Pourquoi cela arrive : Les équipes codent en dur des jetons ou des mots de passe dans des scripts shell par commodité.

Comment éviter : Utilisez des variables CI/CD GitLab masquées et protégées. Pour les scripts externes, utilisez des variables d'environnement ou des gestionnaires de secrets.

Récupération : Si un secret fuit, révoquez-le immédiatement et auditez les journaux d'accès.

Piège 2 : Ignorer les métriques de capacité des runners

Pourquoi cela arrive : Les équipes se concentrent uniquement sur le succès/échec des pipelines et manquent les temps d'attente lents.

Comment éviter : Configurez des alertes sur gitlab_runner_autoscaling_machine_states et les métriques de profondeur de file. Utilisez des règles d'alerte Prometheus : gitlab_ci_pipeline_queue_duration_seconds > 300.

Récupération : Si les alertes se déclenchent, mettez à l'échelle les runners ou optimisez la planification des jobs.

Piège 3 : Alerter excessivement sur chaque échec de pipeline

Pourquoi cela arrive : Les équipes configurent des webhooks pour alerter sur tous les événements de pipeline, ce qui conduit à une fatigue d'alerte.

Comment éviter : Alertez uniquement sur les échecs de la branche par défaut ou des branches protégées, et utilisez des niveaux de gravité. Dans les paramètres du webhook, filtrez par branche ou utilisez un script personnalisé pour filtrer les payloads.

Récupération : Ajustez finement les règles d'alerte et mettez en sourdine les notifications non critiques.

Piège 4 : Ne pas épingler les versions des outils de surveillance

Pourquoi cela arrive : Les équipes installent des agents ou des exportateurs sans vérifier la compatibilité avec leur version de GitLab.

Comment éviter : Consultez la matrice de compatibilité dans la documentation GitLab avant d'installer toute intégration de surveillance.

Récupération : Si une version incompatible est installée, revenez à une version prise en charge et vérifiez que les métriques apparaissent.

Liste de contrôle des opérations

Voici une liste de contrôle pratique pour la surveillance continue de GitLab CI/CD. Attribuez un responsable pour chaque élément et une fréquence de révision.

Comment utiliser cette liste de contrôle :

• Chaque responsable est une personne unique responsable, pas un groupe. Si le responsable change, mettez à jour le tableau.
• Les fréquences de révision sont des minimums ; ajustez-les en fonction des besoins de votre équipe.
• Automatisez autant de vérifications que possible à l'aide de planifications CI ou de tâches cron.

Exemple d'incident : Diagnostiquer un pipeline instable

Appliquons ces pratiques à un scénario réaliste.

Scénario : Votre équipe remarque que le pipeline deploy-to-staging échoue de manière intermittente. Les échecs se produisent environ une fois toutes les dix exécutions, toujours au même job, avec l'erreur connection refused lors de l'envoi vers un registre Docker.

Étape 1 : Observer (lecture seule)

curl --header "PRIVATE-TOKEN: <jeton>" "https://gitlab.example.com/api/v4/projects/123/pipelines?per_page=20&status=failed"

Sortie : Plusieurs pipelines en échec, tous dans le job docker-push. Récupérez la trace du job :

curl --header "PRIVATE-TOKEN: <jeton>" "https://gitlab.example.com/api/v4/projects/123/jobs/789/trace"

Extrait du journal :

Error: error building image: error building stage: failed to execute command: waiting for connection: dial tcp 10.0.1.23:2376: connect: connection refused

Étape 2 : Diagnostiquer

L'erreur pointe vers le démon Docker sur le runner. Vérifiez le statut du runner :

sudo gitlab-runner status

Sortie : gitlab-runner: Service is running

Vérifiez l'espace disque :

df -h

La sortie montre : /var/lib/docker 92% used. Une utilisation élevée du disque peut provoquer une instabilité du démon Docker.

Étape 3 : Plus petit changement justifié

Nettoyez le cache Docker :

docker system prune -af --volumes

Sortie attendue :

Deleted Containers:
...
Total reclaimed space: 15.6GB

Étape 4 : Vérifier

Relancez le pipeline en échec manuellement :

# Dans l'interface GitLab, cliquez sur « Relancer » sur le pipeline en échec, ou utilisez l'API
curl --request POST --header "PRIVATE-TOKEN: <jeton>" "https://gitlab.example.com/api/v4/projects/123/pipelines/98765/retry"

Résultat attendu : Le pipeline réussit.

Étape 5 : Prévenir la récurrence

Configurez une alerte sur l'utilisation du disque pour les runners. Utilisez l'exportateur de nœud Prometheus ou une simple tâche cron :

# La tâche cron sur l'hôte du runner s'exécute toutes les heures
0 * * * * /usr/bin/df -h /var/lib/docker | awk 'NR==2 {print $5}' | mail -s "Runner disk usage" [email protected]

Cette alerte vous permet de savoir avant que l'espace disque ne devienne critique.

Conclusion

La surveillance et les alertes GitLab CI/CD ne sont utiles que lorsque les commandes sont versionnées, observables et réversibles. Copier une commande sans vérifier les prérequis et la sortie attendue n'est pas une procédure opérationnelle ; c'est un pari. Les pratiques de cet article vous donnent un cadre pour l'inventaire, la configuration sûre, la vérification, la récupération après échec et les opérations continues.

Commencez par une vérification à faible risque : inventorier la version de votre GitLab et le statut des runners. Enregistrez l'état actuel, exécutez la vérification en lecture seule documentée et comparez avec le signal attendu. Ajoutez ensuite progressivement les métriques Prometheus, les alertes et la liste de contrôle des opérations. Ne révisez les dépendances telles que GitLab Runner, Docker et Kubernetes que lorsqu'elles affectent votre surveillance et votre récupération.

Un flux de travail de surveillance fiable rend les échecs visibles, protège les valeurs sensibles, limite les modifications à la ressource prévue et définit la vérification de récupération avant qu'un incident ne force la décision. Attribuez un responsable unique pour chaque élément de la liste de contrôle et revisitez-le régulièrement. C'est la différence entre réagir aux pannes et les prévenir.