Problème courant : commande non trouvée (outil manquant sur l'agent)

L'agent Jenkins et son environnement : la source des capacités de build

Jenkins, dans son rôle d'orchestrateur, délègue l'exécution réelle des tâches de build (compilation, tests, packaging, etc.) à des agents (parfois appelés noeuds ou esclaves). Ces agents peuvent être la machine master Jenkins elle-même (non recommandé pour la production) ou des machines distinctes, physiques ou virtuelles, y compris des conteneurs Docker. La capacité d'un pipeline à exécuter une commande spécifique, comme mvn pour Maven, npm pour Node.js, ou docker pour interagir avec Docker, dépend entièrement de la présence et de l'accessibilité de cet outil sur l'agent qui exécute le job.

Une erreur fréquente, surtout lorsqu'on débute ou qu'on configure de nouveaux agents, est le fameux message "commande non trouvée" (ou "command not found"). Ce message signifie simplement que le système d'exploitation de l'agent n'a pas pu localiser l'exécutable de la commande que Jenkins a tenté d'invoquer. Ce n'est généralement pas un problème de Jenkins lui-même, mais un problème d'environnement de l'agent.

Comprendre les causes de cette erreur et savoir comment y remédier est crucial pour garantir que vos pipelines peuvent utiliser tous les outils nécessaires à la construction et au déploiement de vos applications.

Diagnostiquer l'erreur "commande non trouvée" : lire les signaux de la console

Lorsqu'une commande est introuvable, la sortie console de Jenkins est généralement très explicite. Vous verrez typiquement un message indiquant que la commande spécifiée dans une étape de script shell (sh '...') ou batch (bat '...') n'a pas pu être exécutée. Le message d'erreur précis peut varier légèrement selon le système d'exploitation de l'agent, mais l'idée reste la même.

Sur un agent Linux ou macOS, vous pourriez voir :

+ mvn clean install
/tmp/jenkins-script12345.sh: line 2: mvn: command not found
Build step 'Execute shell' marked build as failure

Sur un agent Windows, le message pourrait être :

C:\Jenkins\workspace\my-job>gradlew build
'gradlew' is not recognized as an internal or external command,
operable program or batch file.
Build step 'Execute Windows batch command' marked build as failure

Ces messages indiquent clairement que l'interpréteur de commandes de l'agent (bash, sh, cmd.exe, PowerShell) n'a pas réussi à trouver l'exécutable mvn ou gradlew dans les répertoires listés par la variable d'environnement PATH.

Le contexte est important : quelle étape du pipeline a échoué ? Quelle était la commande exacte ? Si la commande est censée être fournie par un outil installé via la configuration globale des outils Jenkins (Global Tool Configuration), vérifiez que le nom de l'outil est correctement orthographié dans votre Jenkinsfile.

Solutions : installer l'outil et configurer le PATH sur l'agent

La solution la plus directe à une erreur "commande non trouvée" est de s'assurer que l'outil requis est effectivement installé sur l'agent qui exécute le build. Si l'outil n'est pas installé, vous devrez le faire manuellement ou via des scripts d'automatisation de la configuration de vos agents (Ansible, Chef, Puppet, etc.).

Une fois l'outil installé, il faut s'assurer que son répertoire d'installation (contenant l'exécutable) est inclus dans la variable d'environnement PATH de l'utilisateur sous lequel Jenkins exécute les processus sur cet agent. Le PATH est une liste de répertoires que le système d'exploitation parcourt pour trouver les exécutables des commandes. Si le répertoire de l'outil n'y figure pas, la commande ne sera pas trouvée même si l'outil est installé.

Pour vérifier le PATH actuel d'un agent pendant un build, vous pouvez ajouter une étape temporaire à votre pipeline :

Pour Linux/macOS :

sh 'echo $PATH'

Pour Windows :

bat 'echo %PATH%'

Si le répertoire de l'outil est manquant, vous devrez modifier la configuration de l'agent pour ajouter ce répertoire au PATH. La manière de le faire dépend du système d'exploitation et de la façon dont l'agent Jenkins est lancé (par exemple, en modifiant .bashrc, .profile, les variables d'environnement système, ou la configuration du service Jenkins sur l'agent).

Il est également important de noter que si vous utilisez des agents Docker, l'outil doit être présent dans l'image Docker utilisée par l'agent. Vous devrez modifier votre Dockerfile pour inclure l'installation de l'outil, ou utiliser une image de base qui le fournit déjà.

Utiliser la gestion globale des outils de Jenkins (Global Tool Configuration)

Jenkins offre une fonctionnalité appelée "Global Tool Configuration" (accessible via Administrer Jenkins > Global Tool Configuration) qui permet de définir des installations d'outils (JDK, Maven, Node.js, Ant, Gradle, etc.) que les jobs peuvent ensuite référencer. Jenkins peut même, pour certains outils, les télécharger et les installer automatiquement sur les agents si nécessaire (si l'option "Install automatically" est cochée et configurée).

Une fois qu'un outil est configuré globalement avec un nom spécifique (par exemple, `Maven_3_8_4` ou `NodeJS_16`), vous pouvez y faire référence dans votre Jenkinsfile en utilisant la directive tools :

pipeline {
    agent any
    tools {
        maven 'Maven_3_8_4'
        jdk 'AdoptOpenJDK_11'
        nodejs 'NodeJS_16'
    }
    stages {
        stage('Build Maven') {
            steps {
                sh 'mvn --version'
                sh 'mvn clean package'
            }
        }
        stage('Build Node') {
            steps {
                sh 'node --version'
                sh 'npm --version'
                sh 'npm install'
            }
        }
    }
}

Lorsque Jenkins exécute ce pipeline, il s'assurera que les versions spécifiées des outils sont disponibles sur l'agent et ajoutera leurs répertoires binaires au PATH pour la durée du build. Cela simplifie grandement la gestion des dépendances d'outils, surtout si vous avez plusieurs agents ou si vous avez besoin de différentes versions d'un même outil pour différents projets.

Si vous utilisez cette méthode et que vous rencontrez toujours une erreur "commande non trouvée", vérifiez que le nom de l'outil dans la directive tools correspond exactement à celui défini dans la "Global Tool Configuration". Vérifiez également les logs de l'agent pour voir s'il y a eu des problèmes lors de l'installation automatique de l'outil.