Syntaxe des Pipelines Jenkins : Un Guide Complet pour Débutants

La syntaxe des pipelines Jenkins vous permet de décrire votre processus de construction, de test et de déploiement dans un Jenkinsfile qui vit avec votre code. Cela est important car vos modifications de pipeline peuvent être révisées, versionnées et annulées comme du code applicatif.

Si vous débutez avec les pipelines Jenkins, commencez par la syntaxe de pipeline Déclarative. Elle est structurée, lisible et couvre la plupart des workflows CI/CD sans nécessiter beaucoup de connaissances en Groovy.

Pipeline Déclaratif vs Scripté

Jenkins prend en charge deux styles de pipeline.

Le pipeline Déclaratif utilise une structure stricte pipeline { ... }. C'est le meilleur choix par défaut pour la plupart des équipes car Jenkins peut valider la forme du fichier et afficher les étapes proprement dans l'interface utilisateur.

Le pipeline Scripté utilise Groovy à l'intérieur de blocs node { ... }. Il vous donne plus de contrôle, mais il est plus facile de créer des pipelines difficiles à maintenir si votre équipe n'est pas à l'aise avec Groovy.

Utilisez d'abord le Déclaratif. Utilisez le Scripté uniquement lorsque vous avez besoin d'une logique que le Déclaratif ne peut pas exprimer proprement.

Un Pipeline Déclaratif Minimal

Un Jenkinsfile de base a un agent, des étapes et des actions :

pipeline {
    agent any

    stages {
        stage('Build') {
            steps {
                echo 'Construction de l\'application'
                sh 'mvn clean package'
            }
        }

        stage('Test') {
            steps {
                sh 'mvn test'
            }
        }
    }
}

agent any indique à Jenkins d'exécuter le pipeline sur n'importe quel agent disponible. Chaque stage apparaît séparément dans l'interface utilisateur de Jenkins. Le bloc steps contient les commandes que Jenkins exécute.

Sur les agents Windows, utilisez bat au lieu de sh :

bat 'gradlew.bat test'

La Directive `agent`

La directive agent décide où le pipeline ou l'étape s'exécute.

Exécuter sur n'importe quel agent disponible :

agent any

Exécuter sur un agent avec un label spécifique :

agent { label 'linux && docker' }

Ignorer un agent global et en choisir un par étape :

pipeline {
    agent none

    stages {
        stage('Build') {
            agent { label 'linux' }
            steps {
                sh './build.sh'
            }
        }
    }
}

agent none est utile lorsque différentes étapes nécessitent des environnements différents, comme Linux pour les builds et Windows pour les tests d'installateur.

Étapes et Actions

Utilisez les étapes pour diviser le pipeline en un travail qu'un développeur peut comprendre en un coup d'œil : checkout, build, test, package, déploiement.

stages {
    stage('Checkout') {
        steps {
            checkout scm
        }
    }

    stage('Tests Unitaires') {
        steps {
            sh 'npm test'
        }
    }
}

Gardez les étapes significatives. Une étape appelée Run avec cinquante commandes est difficile à déboguer. Un pipeline avec vingt petites étapes est bruyant. Visez des étapes qui correspondent à des points de contrôle réels du workflow.

Variables d'Environnement

Utilisez environment pour les valeurs dont plusieurs étapes ont besoin :

pipeline {
    agent any

    environment {
        APP_NAME = 'orders-api'
        IMAGE = "registry.example.com/team/orders-api:${env.BUILD_NUMBER}"
    }

    stages {
        stage('Build Image') {
            steps {
                sh 'docker build -t "$IMAGE" .'
            }
        }
    }
}

Dans les chaînes Groovy, vous pouvez lire les variables via env.APP_NAME. Dans les étapes shell, Jenkins exporte les variables d'environnement afin que $APP_NAME et $IMAGE fonctionnent dans le shell.

Ne mettez pas de secrets dans environment. Utilisez les identifiants Jenkins avec withCredentials.

Paramètres

Les paramètres permettent à quelqu'un de choisir des valeurs lors du démarrage manuel d'une construction :

pipeline {
    agent any

    parameters {
        string(name: 'BRANCH_NAME', defaultValue: 'main', description: 'Branche Git à construire')
        booleanParam(name: 'RUN_TESTS', defaultValue: true, description: 'Exécuter les tests unitaires')
        choice(name: 'DEPLOY_ENV', choices: ['dev', 'staging', 'prod'], description: 'Environnement cible')
    }

    stages {
        stage('Afficher les Entrées') {
            steps {
                echo "Branche : ${params.BRANCH_NAME}"
                echo "Cible de déploiement : ${params.DEPLOY_ENV}"
            }
        }
    }
}

Utilisez les paramètres pour les choses qui doivent varier entre les exécutions. Ne les utilisez pas pour contourner la révision des modifications de production.

Étapes Conditionnelles avec `when`

La directive when contrôle si une étape s'exécute :

stage('Déploiement en Production') {
    when {
        branch 'main'
    }
    steps {
        sh './deploy-prod.sh'
    }
}

Vous pouvez également utiliser une expression :

stage('Test') {
    when {
        expression { return params.RUN_TESTS }
    }
    steps {
        sh 'npm test'
    }
}

Placez when sur l'étape, pas à l'intérieur de steps.

Actions Post-Exécution

Les blocs post s'exécutent après la fin d'une étape ou d'un pipeline. Ils sont utiles pour publier des rapports de test, archiver des preuves de construction et nettoyer.

pipeline {
    agent any

    stages {
        stage('Test') {
            steps {
                sh 'mvn test'
            }
            post {
                always {
                    junit 'target/surefire-reports/*.xml'
                }
            }
        }
    }

    post {
        failure {
            echo 'Le pipeline a échoué'
        }
        always {
            cleanWs()
        }
    }
}

junit publie les résultats des tests même en cas d'échec des tests. cleanWs() provient du plugin Workspace Cleanup, donc installez ce plugin avant de l'utiliser.

Options

Utilisez options pour définir le comportement du pipeline :

pipeline {
    agent any

    options {
        timestamps()
        timeout(time: 30, unit: 'MINUTES')
        disableConcurrentBuilds()
        buildDiscarder(logRotator(numToKeepStr: '20'))
    }

    stages {
        stage('Build') {
            steps {
                sh './build.sh'
            }
        }
    }
}

Ces options rendent les journaux plus faciles à lire, arrêtent les constructions bloquées, empêchent les exécutions simultanées du même travail et limitent l'historique des anciennes constructions.

Un Pipeline Pratique pour Débutants

Cet exemple vérifie le code, construit un projet Java, publie les résultats des tests et archive le JAR empaqueté :

pipeline {
    agent { label 'linux' }

    options {
        timestamps()
        timeout(time: 30, unit: 'MINUTES')
        disableConcurrentBuilds()
    }

    stages {
        stage('Checkout') {
            steps {
                checkout scm
            }
        }

        stage('Build') {
            steps {
                sh 'mvn clean package'
            }
        }

        stage('Publier') {
            steps {
                junit 'target/surefire-reports/*.xml'
                archiveArtifacts artifacts: 'target/*.jar', fingerprint: true
            }
        }
    }
}

C'est un meilleur point de départ qu'un pipeline de déploiement géant. Une fois la construction fiable, ajoutez la publication d'images, les analyses de sécurité ou les étapes de déploiement.

Bases du Pipeline Scripté

Un pipeline Scripté simple ressemble à ceci :

node('linux') {
    stage('Checkout') {
        checkout scm
    }

    stage('Build') {
        sh 'mvn clean package'
    }
}

N'enveloppez pas un bloc pipeline {} Déclaratif à l'intérieur d'un pipeline Scripté. Gardez les deux styles séparés, sauf si vous avez une raison spécifique et testée de mélanger de petites sections scriptées à l'intérieur de blocs script { ... } Déclaratifs.

Bonnes Habitudes de Pipeline

Stockez le Jenkinsfile dans le contrôle de source. Gardez les secrets dans les identifiants Jenkins. Donnez aux étapes des noms qui correspondent au travail qu'elles effectuent. Publiez les rapports dans les blocs post afin que les échecs laissent encore des preuves utiles. Ajoutez des délais d'attente avant qu'une construction ne reste bloquée toute la nuit.

La plupart des problèmes de pipeline pour débutants proviennent d'hypothèses cachées : un outil existe sur un agent mais pas sur un autre, un secret est codé en dur, ou un rapport n'est publié qu'en cas de succès. Rendez ces hypothèses explicites dans le pipeline, et Jenkins deviendra beaucoup plus fiable.