Introduction à Jenkins

Les tâches freestyle (méthode historique) permettent de configurer le projet en remplissant un formulaire détaillant les étapes de construction du projet. Toutefois, pour les étapes de compilation, vous serez rapidement amené à écrire des lignes de commande BATCH ou Bash pour lancer vos outils de compilation.
De plus, dès lors que votre projet est un peu plus complexe (gestion de plusieurs plateformes, de plusieurs variantes…), vous allez rapidement devoir ajouter de la logique à vos scripts afin de gérer tous les cas. On remarque alors que la configuration des tâches se rapproche de l’écriture d’un programme.

Pipeline donne une solution à cette problématique en offrant un nouveau langage, spécifique, pour écrire la configuration de vos tâches. Grâce à ce langage (basé sur Groovy), vous pourrez rendre la configuration plus simple et lisible, et ce, tout en gérant des cas de plus en plus complexes.
Aussi, le Pipeline peut être sauvegardé dans un fichier, celui-ci pouvant être versionné. Ainsi, vous pouvez lier une configuration spécifique à une version spécifique de votre projet. Plus précisément, la configuration de votre projet sera toujours en accord avec votre projet, et donc toujours compilable, et ce, même si vous devez compiler une ancienne version.

En bref, Pipeline est mieux et plus avancé. À l’heure actuelle, il n’y a aucune raison de commencer un projet « freestyle », et ce, même si les projets freestyle sont globalement (et à première vue) plus simples à mettre en place. Même si Pipeline nécessite d’apprendre un nouveau langage, ce dernier est simple et Jenkins offre de nombreux outils pour une mise en place rapide.

Il suffit de cliquer sur « Nouveau Item », donner un nom puis de sélectionner le type de job (ici, projet free-style). De là, vous serez redirigé vers la page de configuration de votre nouveau job.

La première partie de la page de configuration est négligeable. Elle permet d’indiquer une description du projet (affichée sur la page du projet), de choisir si la tâche a des paramètresParamètres, ou encore de gérer comment le projet est compilé ou est-ce que les anciennes compilations doivent être conservées.

Ensuite arrive la gestion du code source, ou comment nous allons récupérer le code source du projet. Les différents outils disponibles ici dépendent des modules installés. Ayant installé les modules Mercurial et Git, nous ne retrouvons donc que Mercurial et Git.

Après la configuration de la récupération du code, vous pouvez configurer la périodicité de cette récupération, ou autrement dit, qu’est-ce qui déclenche l’exécution de cette tâche. Cela peut être un déclenchement manuel, à la suite d’autres tâches, périodique ou simplement parce que le code a changé (vérification périodique du code sur le serveur de gestion des versions).

Enfin arrive l’étape de compilation. Vous pouvez la configurer en ajoutant des scripts shell ou batch afin de lancer les commandes de compilation du projet. Les commandes sont évidemment exécutées sur la machine esclave. Donc, si votre esclave est une machine Linux, utilisez les scripts shell, sinon, les scripts batch.

Finalement arrivent les étapes suivant la réussite de la tâche. C’est ici que l’on pourra, par exemple, notifier par courriel de l’échec de la tâche ou faire un rapport.

La première difficulté sera de retrouver vos outils suivant les machines sur lesquelles vous exécutez votre tâche.
Pour résoudre cela, vous pouvez configurer des variables d’environnement spécifiques à votre machine dans la page de configuration de la machine.

Sous Linux, vous n’avez pas d’interpréteur Batch. Sous Windows, vous n’avez, par défaut, pas d’interpréteur Shell. Il faudra en installer un, tel que Git for Windows, et de rendre disponible l’exécutable sh.exe (en l’ajoutant dans la variable d’environnement PATH). Ainsi, même sous Windows, vous pouvez exécuter les scripts shell de Jenkins.

V-C-2-a. Exécution de commande spécifique à la machine▲

if [ "${AXIS_NAME}" = "Windows" ]
then
    # Commande Windows
else
    # Commande autre
fi

Évidemment, différencier la plateforme dans les scripts ce n’est pas la meilleure solution, car vous obtiendrez une répétition du code (code de compilation Windows et code de compilation Linux). En jouant sur la configuration des chemins des outils et avec un axe approprié, vous pouvez obtenir un résultat plus générique et aussi, plus simple.

Même si un job freestyle permet une configuration rapide, les tâches complexes demandent de mettre en place une logique avancée ressemblant au déroulement d'un algorithme.
Aussi, au cours de la vie du projet, l'architecture de ce dernier peut évoluer et conjointement, les tâches liées à celui-ci devront évoluer. S'il arrive que vous deviez réexécuter vos tâches sur une ancienne version, la tâche ayant été modifiée, celle-ci échouera certainement.

C'est là qu'entre en jeu Pipeline. Celui-ci offre un langage de programmation simple, mais complet pouvant être sauvegardé sur le logiciel de contrôle de version et donc, synchronisé avec les différentes versions de votre projet.

Encore une fois, cela passe par « Nouveau Item ». Évidemment, le type de tâche à prendre sera « Pipeline ».

La page de configuration reprend des éléments de celle pour les tâches free-style tout en offrant une version épurée. En effet, mise à part la configuration des paramètres, des options globales de la tâche et de la répétitivité de la tâche, on arrive tout de suite à la configuration du pipeline et cela, à travers un simple éditeur de script.

V-D-2-a. Script Pipeline▲

node {  
    stage('Build') { 
        // 
    }
    stage('Test') { 
        // 
    }
    stage('Deploy') {
        //
    }
}

pipeline {
    agent any 
    stages {
        stage('Build') { 
            steps {
                // 
            }
        }
        stage('Test') { 
            steps {
                // 
            }
        }
        stage('Deploy') {
            steps {
                //
            }
        }
    }
}

V-D-2-b. Restreindre l’exécution d’une tâche▲

pipeline {
    agent {label 'slave'}
    stages {
        ...
    }
}

V-D-2-c. Paralléliser des tâches▲

pipeline {
    agent none
    stages {
        stage('Run Tests') {
            parallel {
                stage('Test On Windows') {
                    agent {
                        label "windows"
                    }
                    steps {
                        bat "run-tests.bat"
                    }
                    post {
                        always {
                            junit "**/TEST-*.xml"
                        }
                    }
                }
                stage('Test On Linux') {
                    agent {
                        label "linux"
                    }
                    steps {
                        sh "run-tests.sh"
                    }
                    post {
                        always {
                            junit "**/TEST-*.xml"
                        }
                    }
                }
            }
        }
    }
}

Vous avez plusieurs choix pour écrire votre script. En effet, Jenkins propose des aides afin de faciliter cette étape.

V-D-3-a. Module Blue Ocean▲

V-D-3-b. Générateur de code▲

V-D-3-c. Générateur déclaratif▲

V-D-3-d. Documentation▲

Deux syntaxes sont disponibles pour les Pipeline. Les deux sont équivalentes, mais la documentation officielle stipule que la syntaxe déclarative a été ajoutée pour rendre l'écriture et la lecture des pipelines plus simple. Toutefois, la syntaxe scriptée permet plus de liberté.

Ainsi, la compilation du projet BouskNet peut s’effectuer avec ce script :

node {
 stage('Checkout') { // for display purposes
      cleanWs()
          
      checkout([$class: 'MercurialSCM',
                 credentialsId: '', 
                 revision: 'Lib', 
                 source: 'https://bitbucket.org/Bousk/bousknet'])
      }
   stage('Premake') {
      dir('./NetworkLib') {
            sh "${JENKINS_HOME}/Tools/premake/premake5 gmake"
            // Hack pour compiler sur une plateforme ARM
            sh "sed -i -e 's/m64/marm/g' ./Projects/gmake/Network.make"
            sh "sed -i -e 's/m64/marm/g' ./Projects/gmake/Samples_TCP_Client.make"
            sh "sed -i -e 's/m64/marm/g' ./Projects/gmake/Samples_TCP_Server.make"
            sh "sed -i -e 's/m64/marm/g' ./Projects/gmake/Samples_UDP_HelloWorld.make"
        }
   }
   stage('Build') {
       dir('./NetworkLib/Projects/gmake/') {
            sh "make"
        }
   }
}

Si votre serveur requiert une authentification, vous devez obtenir un jeton pour l’utilisateur souhaitant scripter ses demandes d’exécution de tâches. Celui-ci peut être obtenu dans la page de configuration de l’utilisateur.

Une fois obtenu, vous devez obtenir l’accès au serveur avec :

curl "http://USER:TOKEN@SERVER/crumbIssuer/api/xml?xpath=concat(//crumbRequestField,%22:%22,//crumb)"

Cette requête devrait vous permettre d’obtenir un jeton de sécurité à inclure dans vos prochaines requêtes :

curl -X POST -H CRUMB http://USER@SERVER/job/TACHE/build

• CRUMB : le résultat de la première requête ;
• USER : le nom de l’utilisateur dans Jenkins ;
• TOKEN : le jeton correspondant à l’utilisateur ;
• SERVER : le nom du serveur ;
• TACHE : le nom de la tâche à lancer.

Vous pouvez changer le nombre d’exécuteurs (c’est-à-dire, le nombre de tâches pouvant être exécutées sur une machine en parallèle) pour correspondre au mieux à la puissance de la machine esclave.

Des étiquettes peuvent être assignées aux esclaves. Comme vu dans la section de mise en place de tâches multiconfigurationsGénéralisation, elles permettent de préciser quelle machine peut exécuter quelles tâches.

Il est possible de définir/redéfinir des variables d’environnement spécifiques à la machine. Ainsi, les tâches pourront s’exécuter même si les outils sont installés différemment des autres machines de votre parc.

Certains modules récupérant les sources de vos projets permettent de ne pas déclencher la tâche si un message particulier est écrit dans le message de commit. Vous pouvez retrouver cette option dans la section « gestion de code source », bouton « avancé » de la configuration d’une tâche. Jenkins vous laissera ainsi renseigner une expression régulière, qui lorsque vérifiée, fera que Jenkins ignore ce commit.
De la même façon, vous pouvez aussi ignorer les commits de certains utilisateurs.

Les artefacts sont les fichiers générés lors de l’exécution d’une tâche. En effet, par défaut (c’est-à-dire sans artefact) Jenkins ne sauvegardera que les journaux de l’exécution de la tâche et cela, seulement si vous ne supprimez pas les anciennes exécutions.
Par conséquent, vous n’avez accès qu’à un nombre limité de journaux et seul le dernier espace de travail (workspace) sera accessible.

En configurant l’archivage des artefacts, vous pouvez conserver les fichiers générés (tels que les exécutables) ou encore, les journaux. Cette option se retrouve dans les étapes postexécutions de la tâche.

Avec le nombre grandissant de tâches sur votre serveur Jenkins, il arrivera un moment où vous souhaiterez bloquer l’exécution d’une tâche si une autre est en cours d’exécution. En effet, une tâche particulière pourrait impacter le bon déroulement d’une autre.
Pour ce faire, vous devez installer le module « Build Blocker ». Ce dernier ajoute une entrée dans la configuration des tâches permettant de définir si l’exécution de cette tâche est bloquée par une autre tâche.
La liste des tâches bloquantes peut être définie grâce à une expression régulière.