Jenkins/doc/tutorials/standard-make-pipeline.md

6.4 KiB

Utilisation du pipeline standardMakePipeline()

Note Vous travaillez sur un projet Symfony ? Dans ce cas référez vous au tutoriel "Utiliser le pipeline Symfony.

Le pipeline standardMakePipeline() a pour objectif de permettre d'obtenir simplement et rapidement un pipeline générique pour un projet de développement ou d'intégration en utilisant et respectant quelques conventions de nommage dans ses tâches Make.

Globalement, le pipeline exécute les opérations suivantes:

  • Il exécute la commande make build sur votre projet;
  • Il exécute la commande make test sur votre projet et si votre branche est une PR, il créait un commentaire sur celle ci avec la sortie de ces tests;
  • Si votre branche est une branche de "release" (par défaut les branches develop, testing et stable) il exécute la commande make release puis diffuse une notification sur le canal #cadoles-jenkins.

Le pipeline ne présume pas des opérations réalisées par ces 3 tâches. Il ne fait que les exécuter en partant du principe que votre projet suit un cycle conventionnel de développement. Mais globalement ces tâches devraient:

  • make build: Construire votre projet (installer les dépendances, générer les assets, compiler le code source le cas échéant, etc);
  • make test: Exécuter les tests automatisés associés à votre projet (unitaire, intégration, etc);
  • make release: Diffuser une nouvelle version de votre projet (construire et déployer des artefacts comme des paquets ou des images de conteneur, exécuter un déploiement Ansible, etc).

Note: La gestion des dépendances des tâches est à la charge du développeur (voir "Comment installer les dépendances NPM avant une tâche ?" dans la FAQ pour un exemple).

Utilisation

Afin d'utiliser le pipeline, vous devez effectuer les opérations suivantes à l'initialisation de votre projet:

  1. Créer votre fichier Jenkinsfile à la racine de votre projet

    @Library("cadoles") _
    
    standardMakePipeline()
    
  2. Créer votre fichier Makefile à la racine de votre projet

    test:
        echo "Testing my project..."
    
    build:
        echo "Building my project..."
    
    release:
        echo "Releasing my project..."
    
  3. Ajouter les deux fichiers à votre historique Git (commit) et pousser sur la branche de développement.

  4. Accéder à Jenkins puis à l'organisation contenant votre projet. Dans la barre de gauche cliquer sur le bouton "Scan Gitea Organization Now"

    Note: Globalement un projet doit être partagé avec l'équipe "Bots" sur la forge afin que Jenkins puisse accéder aux sources de votre projet. Dans la majorité des organisations pré-existentes ce partage est déjà configuré.

  5. Votre pipeline devrait s'exécuter sur Jenkins !

Variables d'environnement pré-disponibles

Le pipeline injecte directement dans l'environnement d'exécution une série de variables d'environnement:

Variable Description Valeurs possibles
PROJECT_VERSION_TAG Tag conventionnel de la version du projet Voir "R14. Respecter le schéma d'identification des images publiées"
PROJECT_VERSION_SHORT_TAG Tag court conventionnel de la version du projet Voir "R14. Respecter le schéma d'identification des images publiées"
BRANCH_NAME Nom de la branche courante Nom de la branche courante (préfixé par PR- le cas échéant)
IS_PR Est ce que l'exécution courante s'effectue pour une PR ? true ou false
CI Est ce que l'exécution courante s'exécute sur le serveur d'intégration continue ? true

FAQ

Comment installer des dépendances supplémentaires dans l'environnement d'exécution ?

Par défaut l'environnement d'exécution du pipeline est un conteneur basé sur une image Ubuntu LTS (22.04 à ce jour). Dans cette image sont installées des dépendances de base généralement utilisées par les projets de développement.

Cependant si vous avez besoin d'autres dépendances systèmes il est possible d'étendre le fichier Dockerfile par défaut. Pour ce faire, éditer votre fichier Jenkinsfile:

@Library("cadoles") _

// Exemple: installation du paquet ansible-lint 
// dans l'environnement d'exécution
standardMakePipeline([
    'dockerfileExtension': '''
    RUN apt-get update -y \
        && apt-get install -y ansible-lint
    '''
])

Comment injecter des secrets dans l'environnement d'exécution ?

Parfois vous aurez besoin d'utiliser des secrets afin d'accéder soit à des projets privés sur la forge, soit pour publier des paquets ou des images de conteneur. Jenkins intègre une gestion des secrets et ceux ci peuvent être récupérés dans votre environnement d'exécution sous diverses formes (variable d'environnement, fichiers, etc).

Pour ce faire, éditer votre fichier Jenkinsfile:

@Library("cadoles") _

// Exemple: récupération des identifiants du compte
// "jenkins" sur la forge sous la forme des variables
// d'environnement FORGE_USERNAME et FORGE_PASSWORD
standardMakePipeline([
    'credentials': [
        usernamePassword([
            credentialsId: 'forge-jenkins',
            usernameVariable: 'FORGE_USERNAME',
            passwordVariable: 'FORGE_PASSWORD',
        ]),
    ]
])

Les différents types d'entrées possible pour le tableau credentials sont décris sur cette page.

Comment installer les dépendances NPM avant une tâche ?

Pour cela vous pouvez utiliser les mécanismes de gestion des dépendances intégrées à Make. Par exemple:

test: node_modules
    npm run test

node_modules:
    npm ci

De cette manière Make exécutera la commande npm ci si et seulement si le répertoire node_modules n'existe pas déjà.