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

124 lines
6.4 KiB
Markdown

# Utilisation du pipeline `standardMakePipeline()`
> **Note** Vous travaillez sur un projet Symfony ? Dans ce cas référez vous au tutoriel ["Utiliser le pipeline Symfony](https://forge.cadoles.com/Cadoles/Jenkins/wiki/Utiliser-le-pipeline-%22Symfony%22).
Le pipeline [`standardMakePipeline()`](../../vars/standardMakePipeline.groovy) 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
```groovy
@Library("cadoles") _
standardMakePipeline()
```
2. Créer votre fichier `Makefile` à la racine de votre projet
```makefile
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](https://jenkins.cadol.es/) 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"](https://forge.cadoles.com/CadolesKube/KubeRules/wiki/Bonnes-pratiques-de-d%C3%A9veloppement-applicatif-en-vue-d%27un-d%C3%A9ploiement-sur-Kubernetes#r14-respecter-le-sch%C3%A9ma-d-identification-des-images-publi%C3%A9es)|
|`PROJECT_VERSION_SHORT_TAG`|Tag court conventionnel de la version du projet|Voir ["R14. Respecter le schéma d'identification des images publiées"](https://forge.cadoles.com/CadolesKube/KubeRules/wiki/Bonnes-pratiques-de-d%C3%A9veloppement-applicatif-en-vue-d%27un-d%C3%A9ploiement-sur-Kubernetes#r14-respecter-le-sch%C3%A9ma-d-identification-des-images-publi%C3%A9es)|
|`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](../../resources/com/cadoles/standard-make/Dockerfile) 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`:
```groovy
@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](https://jenkins.cadol.es/manage/credentials/) 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`:
```groovy
@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](https://www.jenkins.io/doc/pipeline/steps/credentials-binding/).
### 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:
```makefile
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à.