124 lines
6.4 KiB
Markdown
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é-disponible
|
|
|
|
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à.
|