INTEGRATION CONTINUE AVEC GITLAB CE ET JENKINS

Contexte et objectifs

Dans le contexte actuel, l’Intégration Continue est devenue une étape primordiale et incontournable dans la mise en place d’une chaîne d’intégration complète et robuste. En effet, la mise-à-jour du code source (développement ou infrastructure) via un source code management doit permettre et entrainer l’exécution d’une ou plusieurs tâches de manière automatisée. Il existe aujourd’hui un grand nombre d’outils permettant de réaliser de l’intégration continue. Dans le cadre de ce tutoriel nous utiliserons l’application GitLab en association avec l’orchestrateur Jenkins pour la mise en place d’une chaine d’Intégration Continue simple. Nous disposerons d’un repository central sur l’application GitLab qui, quand celui-ci sera mis-à-jour par un utilisateur, entrainera l’exécution automatique (build) d’un Job grâce à l’orchestrateur Jenkins.

Durée de la mise en place : 30 minutes.

Configuration

0 – Mise en place et détails de l’environnement

Présentation de l’environnement

Notre infrastructure sera composée d’un serveur Debian 9 qui a été déployé sur le provider cloud AWS grâce à CloudFormation. Sur celui-ci, nous avons déployé l’application GitLab CE écoutant sur le port 80 du serveur ainsi que l’application Jenkins écoutant sur le port 8080. Ces deux applications ont été déployées dans deux conteneurs Docker indépendants l’un de l’autre. Dans notre exemple, les deux applications ont été déployées sur le même serveur mais il est possible de déployer les applications sur des serveurs différents.

Infrastructure

Un serveur Debian 9 où sera déployée l’application GitLab CE ainsi que l’application Jenkins.

[table id=description-srv-jenkins-gitlab-ci /]

[table id=description-appli-jenkins-gitlab-ci /]

1 – Création de l’utilisateur Jenkins sur « GitLab CE »

Sur l’application GitLab, se logguer en tant que « Administrator (@root) », et créer un utilisateur « jenkins ». Sur la page principale, cliquer sur « Add people » puis cliquer sur « New user ».

Dans la section « Account », remplir le formulaire comme ci-dessous :

Dans la section « Access », choisir le rôle « Admin » en cochant la case pour permettre à l’utilisateur « jenkins » d’avoir les droits sur l’ensemble des projets.
Information : Il est possible de créer un utilisateur avec des droits plus restreints.

En bas de la page, cliquer sur « Create Use » pour créer l’utilisateur.

Nous allons maintenant définir un mot de passe pour l’utilisateur « jenkins » qui devra le modifier lors de sa première connexion à l’application GitLab. Cliquer sur « Edit » en haut à droit de la page puis dans la section « Password » choisir un mot de passe robuste pour l’utilisateur « jenkins » .

En bas de la page, cliquer sur « Saves changes » pour valider le mot de passe renseigné.

2 – Génération du Token pour établir la liaison entre GitLab et Jenkins

Après l’attribution du mot de passe à l’utilisateur « jenkins », nous allons générer et récupérer un token lié à ce même utilisateur afin de pouvoir établir la liaison avec l’application Jenkins.

Deux solutions s’offrent à nous pour générer et récupérer le token :

Se déconnecter du compte « Administrator » et se logguer avec l’utilisateur « jenkins »
Rester sur le compte « Administrator » et utiliser la fonctionnalité « Impersonate » de GitLab qui permet de simuler l’utilisateur « jenkins » et d’avoir la même vue graphique, directement depuis le compte « Administrator ».

Information : Nous choisirons d’utiliser la solution numéro 2 et donc la fonction « Impersonate » afin de générer et récupérer le token de l’utilisateur « jenkins » directement depuis le compte « Administrator » et ne pas avoir à nous delogguer et nous relogguer sur le compte de l’utilisateur « jenkins ».

Se rendre sur la page de l’utilisateur « jenkins » et cliquer sur le bouton « Impersonate » situé en haut à droite de la page.

Nous devons alors changer le mot de passe de l’utilisateur « jenkins » car il s’agit en réalité de sa première connexion. Choisir un nouveau mot de passe et cliquer sur « Set new password ».
Information : Dans certains cas, il est possible d’être déconnecté de la session en cours « Administrator ». Si c’est le cas, alors se ré-authentifier avec le compte « Administrator », puis se rendre sur l’utilisateur « jenkins » et cliquer à nouveau sur « Impersonate ».

Nous sommes alors dirigés vers la page d’accueil avec en tant qu’utilisateur « jenkins » avec le message suivant « You are now impersonating jenkins » en rouge. Ce qui confirme bien que nous utilisons l’utilisateur « jenkins ».

Cliquer sur la petite icone de l’utilisateur « jenkins » en haute à droit puis sur « Settings » :

Dans le menu latéral à gauche de la page, cliquer sur l’icône ou sur « Access Token ».

Remplir le formulaire avec les informations suivantes :

Donner un nom au token dans le champ « name » et cocher la case « api ». Cette étape est important car c’est elle qui va permettre d’établir la connexion avec l’application Jenkins. Cliquer sur « Create personnal acces token » en bas de la page.

information :

Le champ « Expires at » permet de donner une durée de validité au token mais il n’est pas obligatoire. Dans notre cas nous laisserons ce champ vide signifiant donc une durée illimitée pour la validité du token.
L’option « sudo » est uniquement disponible en tant d’administrateur. Elle permet d’avoir tous des droits sur l’ensemble des utilisateurs.

Le token a été généré avec succès :

→ Token : 6gckNCCvA1uFFYypmNU5

Important : Le token ne sera accessible qu’une seule fois et ne pourra plus être récupéré après avoir quitté cette page. Veillez à bien le copier, car en cas de perte il sera nécessaire d’en générer un nouveau.

En bas de cette page, il est aussi possible de voir les informations relatives au token, telles que le nom, la date de création, la date d’expiration ainsi que les fonctions permises pour celui-ci :

3 – Téléchargement des plugins et mise en place du logging sur Jenkins

Téléchargement du plugin

Nous allons maintenant télécharger le plugin « GitLab » sur l’application Jenkins. Ce plugin, va nous permettre d’établir la liaison avec l’application GitLab et l’utilisateur « jenkins » de l’application GitLab.

Se rendre sur l’application « Jenkins ». Depuis la page principale, suivre le chemin « Administrer Jenkins > Gestion des plugins > Disponibles » et choisir « GitLab ». Cocher ce plugin puis cliquer sur « Télécharger maintenant et installer après redémarrage ».

Sur la page suivante, cocher la case « Redémarrer Jenkins quand l’installation est terminée et qu’aucun job n’est en cours » qui permettra de redémarrer l’application Jenkins après avoir téléchargé le plugin.

Mise en place des logs

Il peut être intéressent en cas de bugs, de mettre en places les logs liés à la l’application GitLab et ainsi de pouvoir déboguer en cas de problème de liaison entre les applications Jenkins et GitLab.

Depuis la page principale, se rendre dans « Administrer Jenkins > Logs système » et choisir « Ajouter un nouvel enregistreur de log » et remplir le formulaire comme ci-dessous :

Nom	gitlab_log
Loggers	com.dabsquared.gitlabjenkins
Niveau de log	FINEST

Cliquer sur « Enregistrer » afin de valider, puis cliquer sur « Clear This Log ». Il sera maintenant possible de suivre toutes les actions liées à l’application GitLab et ainsi pouvoir débuguer en cas de problème.

4 – Configuration du plugins GitLab sur l’application Jenkins

Dans cette partie nous allons configurer le plugin précédemment installé et tester que la connexion avec l’application GitLab est fonctionnelle.

Configuration des credentials

Pour configurer le plugin nous allons devoir créer un credential pour le token.

Depuis la page principale se rendre dans « Identifiants > System > Identifiants globaux (illimité) > Ajouter des identifiants » et compléter le formulaire comme ci-dessous :

Type	GitLab API token
Portée	Global (Jenkins, esclaves, items, etc…)
API token	6gckNCCvA1uFFYypmNU5
ID	token_gitlab
Description	Token GitLab jenkins user

Important :

Veilliez à bien choisir comme type « GitLab API token » car c’est le seul type de crendential accepté pour configurer la connexion
Veilliez à bien copier le token qui a été préalablement à la fin de l’étape 2

Cliquer sur « OK » pour valider.

Configuration du plugin « GitLab »

Il est maintenant nécessaire de configurer le plugin « GitLab » pour que l’orchestrateur Jenkins puisse établir la connexion avec l’application GitLab.

Depuis la page principale se rendre dans « Administrer Jenkins > Configurer le système » puis dans la section « Gitlab ». Compléter le formulaire avec les informations ci-dessous :

Enable authentication for ‘/project’ end-point	Coché
Connection name	gitlab_jenkins	Nom pour la connexion
Gitlab host URL	http://54.224.12.220/	URL de votre application « GitLab »
Credentials	GitLab API token (Token GitLAB jenkins user)	Crédential Token defini précédemment

Tester la connexion en cliquant sur « Test Connection ».
→ Le message « Success » doit apparaitre afin de confirmer que la connexion est fonctionnelle (voir capture précédente). Cliquer sur « Enregistrer » afin de valider les modifications.

Information : Nous pouvons vérifier les logs que nous avons créés afin d’avoir un aperçu des messages qu’il est possible d’avoir avec l’application GitLab.

Se rendre dans « Administrer Jenkins > Gestion des plugins > gitlab_log » :

5 – Création d’un Job sur Jenkins et paramétrage du Trigger

Dans cette partie, nous allons créer un Job sur l’application Jenkins en utilisant la fonction de Trigger permettant de déclencher une action suite à un évènement défini. Dans notre cas, nous déclencherons l’exécution de ce Job lors d’un « push » après la mise-à-jour du code sur le repository hébergé sur l’application GitLab.

Création du « Job »

Sur la page principale, se rendre dans « Nouveau Item » ou cliquer sur « créer un nouveau job » :

Donner un nom à votre projet et choisir le type de projet que vous souhaitez mettre en place. Dans le cadre de ce tutoriel et pour faire simple, nous choisirons « Construire un projet free-style ». Cliquez sur « OK » pour valider.

Sur la page de configuration du Job :

Dans la section « General »

Vérifier bien que « GitLab Connection » correspond bien au nom choisi lors de la configuration de la connexion entre les applications Jenkins et GitLab. Dans notre cas il s’agit bien de « gitlab_jenkins ».

Dans la section « Ce qui déclenche le build »

C’est ici que nous allons configurer le déclenchement de notre évènement, en l’occurrence l’exécution de notre Job (Run du Build) lors d’un évènement de type « Push ».

Cocher la case « Build when a change is pushed to GitLab. GitLab webhook URL: http://3.90.148.95:8080/project/project-webhooks » et récupérer l’URL suivante « http://3.90.148.95:8080/project/project-webhooks ».
Cette URL est importante car il faudra la renseigner dans la configuration de notre projet sur l’application GitLab.

Remplir le formulait comme ci-dessous :

Dans la partie « Enabled GitLab triggers » :

→ Choisir les éléments qui déclencheront l’exécution du Job. Nous choisirons l’évènement « Push Event » qui permet d’exécuter le Job lorsque qu’il y a eu un « push » sur le repository hébergé sur GitLab.

Cliquer sur le bouton « Avancé » pour déployer la suite des configurations.

Dans la partie « Secret token » :

→ Cliquer sur « Generate » afin de générer un token et récupérez-le « d28ee929a595c57ff982b4352b399cf0 ».
Ce token est important car il faudra la renseigner dans la configuration du projet qui sera créé sur l’application GitLab.

Information : Dans le cadre de ce tutoriel, nous laisserons les autres paramètres comme ils étaient par défaut. Vous noterez qu’il existe un grand nombre de configurations différentes qu’il est possible d’implémenter.

Dans la section « Build »

Dans le cadre de cette démonstration, le Job sera uniquement composé d’un simple script shell, composé lui-même d’une simple commande de type bash.

Sélectionner « Ajoutez une étape au build > Exécuter un script shell », ajouter les lignes suivantes dans le champ « Commande » :

#!/bin/bash

curl http://169.254.169.254/latest/meta-data/public-hostname

Cliquer « Sauver » en bas de la page afin de valider la création du Job.

Important : Lors de la création d’un nouveau Job, il est alors nécessaire de l’exécuter une première fois à la main.

Sur la page du projet que nous venons de créer, cliquer sur « Lancer un build ». Le « build » s’exécute une première fois avec succès.

6 – Création d’un projet sur GitLab et activation des webhooks

Dans cette partie, nous allons créer un projet ainsi qu’un repository sur l’application GitLab et activer la fonction webhook qui permettra d’envoyer une notification à l’orchestrateur Jenkins. Cette notification, informera Jenkins qu’un « push » vient d’être effectué sur le repository, pour que celui-ci puisse exécuter le Job créé précédemment. Le tout de façon totalement automatique. Nous pouvons appeler cette suite d’actions un « pipeline d’exécution »

Création et initialisation du projet

Sur la page d’accueil de GitLab, cliquer sur « Create a project » pour créer un nouveau projet. Complétez le formulaire avec les informations choisies puis cliquez sur « Create project ».

Initialiser le projet en cliquant sur « Add README », ajouter un commentaire dans le fichier « README.md » et cliquer sur « Commit changes » pour valider la création du fichier.

Notre repository est désormais composé du fichier README.md avec le commentaire suivant « Continuous Integration with Jenkins, GitLab (Trigger, Webhooks…) ».

Configuration du « Webhook »

Nous allons maintenant configurer le webhook sur le projet préalablement créé. Depuis la page du projet, se rendre dans « Settings > Integrations ». Configurer le formulaire avec les informations suivantes :

URL	http://3.90.148.95:8080/project/project-webhooks	URL récupérée lors de la création de notre Job sur « Jenkins »
Secret Token	d28ee929a595c57ff982b4352b399cf0	Token récupéré lors de la création de notre Job sur « Jenkins »

Cocher la case «Push events ». Cette action permettra d’informer que Gitlbab enverra un webhook à l’orchestrateur Jenkins pour l’informer de jouer le Job lors d’un « push » sur ce repository. Laisser l’espace de texte vide cela permettra de dire que le webhook sera déclenché lors d’un « push » sur n’importe quelle branche de ce projet.

Cliquer sur «Add webhook » pour valider et créer le webhook.

Test du webhook

Nous allons tester que l’intégration est fonctionnelle.

En bas de la page, sur le webhook précédemment de créé, cliquer sur « Test > Push events » :

Le messages suivant doit apparaitre « Hook executed successfully: HTTP 200 » pour confirmer que le webhook est fonctionnel :

7 – Intégration Continue complète pipeline d’execution

Dans cette partie, nous allons simuler un pipeline d’exécution permettant de réaliser une chaîne d’Intégration Continue avec les outils Jenkins et GitLab. Les étapes seront les suivantes :

Clone du projet « continous-integration » sur la machine virtuelle
Modification du code de notre repository (fichier README.md)
Commit et Push du code mis à jour sur notre repository
Déclenchement et exécution automatique du Job « jenkins-webhooks » à la suite au push

En CLI sur notre serveur d’application

1 – Clone du projet sur la VM

Utilisation de la commande « git clone » :

# git clone ssh://git@ec2-3-90-148-95.compute-1.amazonaws.com:2222/jenkins/continous-integration.git

Cloning into 'continous-integration'...
remote: Enumerating objects: 3, done.
remote: Counting objects: 100% (3/3), done.
remote: Compressing objects: 100% (2/2), done.
remote: Total 3 (delta 0), reused 0 (delta 0)
Receiving objects: 100% (3/3), done.

Information : Nous utilisons le SSH pour cloner notre projet afin de respecter les bonnes pratiques recommandées. Nous avons préalablement généré une paire de clés privée/publique et déployé la clé publique sur l’application GitLab.
Si vous souhaitez respecter les recommandation préconisées, je vous invite à vous rendre sur la documentation officielle à l’adresse suivante : https://docs.gitlab.com/ee/ssh/.

2 – Mise-à-jour du projet

Insérer en début de fichier de la ligne « # Example Continiuous Integration’ » dans le fichier « README.md » avec de la commande « sed -i » :

# cd continous-integration/
# sed -i '1i# Example Continiuous Integration' README.md

3 – Commit et Push de la mise-à-jour

– Ajouter un utilisateur permettant de tracer les actions effectuées sur ce repository. Dans notre cas, nous ajoutons l’utilisateur « samiamr » avec la commande « git config –global user.name »
– Ajouter le fichier « README.md » que nous venons de modifier avec la commande « git add »
– Entériner les modifications que nous venons d’effectuer sur le fichier et mettre un commentaire sur le « commit » réalisé avec la commande « git commit -m »
– Vérifier le nom du repository distant avec la commande « git remote -v »
– Pousser les modifications effectuées sur le repository central « GitLab » sur la branche master avec la commande « git push »

$ git config --global user.name "samiamr"

$ git add README.md

$ git commit -m "add description Readme file"
[master 102bef7] add description Readme file

$ git remote -v
origin	ssh://git@ec2-3-90-148-95.compute-1.amazonaws.com:2222/jenkins/continous-integration.git (fetch)
origin	ssh://git@ec2-3-90-148-95.compute-1.amazonaws.com:2222/jenkins/continous-integration.git (push)

$ git push origin master

Vérifier maintenant que les modifications ont bien été prises en compte sur notre repository « GitLab »

Nous pouvons constater qu’un « commit » vient d’être exécuté avec l’instruction « add description Readme file », par l’utilisateur « samiamr » et maintenant « just now ».

4 – Déclenchement et exécution automatique de notre Job

En parallèle, le Job créé sur Jenkins s’est exécuté automatiquement suite à la mise-à-jour et au push du code sur le repository.
Se rendre sur Jenkins et vérifier que l’exécution du Job s’est déclenchée automatiquement :

Nous pouvons constater que le Job a été exécuté par « GitLab » et « pushé » par l’utilisateur « jenkins » avec succès le 3 avril 2020 à 14h28.
Pour information, voici le résultat du Job :

L’intégration Continue avec la mise en place de webhook, déclenchés par des Triggers, avec les outils Jenkins et GitLab est donc fonctionnelle.

C’est maintenant à vous de jouer et d’explorer les multitudes de configurations que nous offrent ces deux puissants outils. Enjoy .

Environnement

Infrastructure

Le serveur utilisé pour réaliser ce tutoriel est une instance EC2 qui a été provisionnée avec le provider AWS et grâce à CloudFormation permettant d’avoir une architecture de type IaC. Ces stacks CloudFormation récupèrent dynamiquement les sources des applications à déployer sur mon repository GitHub. Les applications sont déployées dans des conteneurs Docker afin de privilégier l’agilité.
Information : Toutes les ressources utilisées lors de ce tutoriel ont été déprovisionnées.

Distribution et version des serveurs

[table id=info-os-jenkins-gitlab /]

Version des applications

[table id=tableidinfo-appli-jenkins-gitlab-ci /]