introduction
Jenkins est un serveur d'automatisation open source destiné à automatiser les tâches techniques répétitives liées à l'intégration et à la fourniture continues de logiciels. Avec un écosystème robuste de plugins et un support étendu, Jenkins peut gérer un ensemble divers de charges de travail pour créer, tester et déployer des applications.
Dans les guides précédents, nous avonsinstalled Jenkins on an Ubuntu 16.04 server etconfigured Jenkins with SSL using an Nginx reverse proxy. Dans ce guide, nous montrerons comment configurer Jenkins pour tester automatiquement une application lorsque les modifications sont placées dans un référentiel.
Pour ce didacticiel, nous allons intégrer Jenkins à GitHub afin que Jenkins soit averti lorsqu'un nouveau code est envoyé dans le référentiel. Lorsque Jenkins est averti, il extrait le code, puis le teste dans les conteneurs Docker pour isoler l'environnement de test de la machine hôte Jenkins. Nous utiliserons un exemple d'application Node.js pour montrer comment définir le processus CI / CD pour un projet.
Conditions préalables
Pour suivre ce guide, vous aurez besoin d’un serveur Ubuntu 16.04 avec au moins 1 G de RAM configuré avec une installation Jenkins sécurisée. Pour sécuriser correctement l'interface Web, vous devez attribuer un nom de domaine au serveur Jenkins. Suivez ces guides pour apprendre à configurer Jenkins dans le format attendu:
Pour contrôler au mieux notre environnement de test, nous exécuterons les tests de nos applications dans des conteneurs Docker. Une fois que Jenkins est opérationnel, installez Docker sur le serveur en suivant les étapes 1 et 2 de ce guide:
Lorsque vous avez terminé les guides ci-dessus, vous pouvez continuer avec cet article.
Ajouter l'utilisateur Jenkins au groupe Docker
Après avoir suivi les conditions préalables, Jenkins et Docker sont installés sur votre serveur. Cependant, par défaut, l'utilisateur Linux responsable de l'exécution du processus Jenkins ne peut pas accéder à Docker.
Pour résoudre ce problème, nous devons ajouter l'utilisateurjenkins
au groupedocker
en utilisant la commandeusermod
:
sudo usermod -aG docker jenkins
Vous pouvez lister les membres du groupedocker
pour confirmer que l'utilisateurjenkins
a été ajouté avec succès:
grep docker /etc/group
Outputdocker:x:999:sammy,jenkins
Pour que Jenkins utilise sa nouvelle composition, vous devez redémarrer le processus:
sudo systemctl restart jenkins
À l'aide de certains des plug-ins par défaut que nous avons activés lors de l'installation, Jenkins peut désormais utiliser Docker pour exécuter des tâches de construction et de test.
Créer un jeton d'accès personnel dans GitHub
Pour que Jenkins puisse suivre vos projets GitHub, vous devez créer un jeton d'accès personnel dans notre compte GitHub.
Commencez par visiterGitHub et connectez-vous à votre compte si vous ne l'avez pas déjà fait. Ensuite, cliquez sur l'icône de votre utilisateur dans le coin supérieur droit et sélectionnezSettings dans le menu déroulant:
Sur la page qui suit, recherchez la sectionDeveloper settings du menu de gauche et cliquez surPersonal access tokens:
Cliquez sur le boutonGenerate new token sur la page suivante:
Vous serez dirigé vers une page où vous pourrez définir la portée de votre nouveau jeton.
Dans la caseToken description, ajoutez une description qui vous permettra de le reconnaître plus tard:
Dans la sectionSelect scopes, cochez les casesrepo:status,repo:public_repo etadmin:org_hook. Cela permettra à Jenkins de mettre à jour les statuts de validation et de créer des webhooks pour le projet. Si vous utilisez un référentiel privé, vous devrez sélectionner l'autorisation généralerepo au lieu des sous-éléments du référentiel:
Lorsque vous avez terminé, cliquez surGenerate token en bas.
Vous serez redirigé vers la page d'index des jetons d'accès personnel et votre nouveau jeton s'affichera:
Copiez le jeton maintenant afin que nous puissions le référencer plus tard. Comme le message l'indique, il n'existe aucun moyen de récupérer le jeton une fois que vous avez quitté cette page.
[.note] #Note: Comme mentionné dans la capture d'écran ci-dessus, pour des raisons de sécurité, il n'y a aucun moyen de réafficher le jeton une fois que vous quittez cette page. Si vous perdez votre jeton, supprimez le jeton actuel de votre compte GitHub, puis créez-en un nouveau.
#
Maintenant que vous avez un jeton d’accès personnel pour votre compte GitHub, nous pouvons configurer Jenkins pour surveiller le référentiel de votre projet.
Ajouter le jeton d'accès personnel GitHub à Jenkins
Maintenant que nous avons un jeton, nous devons l’ajouter à notre serveur Jenkins afin qu’il puisse configurer automatiquement les Webhooks. Connectez-vous à votre interface Web Jenkins à l'aide du compte administratif que vous avez configuré lors de l'installation.
Depuis le tableau de bord principal, cliquez surCredentials dans le menu de gauche:
Sur la page suivante, cliquez sur la flèche en regard de(global) dans la portée deJenkins. Dans la boîte qui apparaît, cliquez surAdd credentials:
Vous serez amené à un formulaire pour ajouter de nouvelles informations d'identification.
Dans le menu déroulantKind, sélectionnezSecret text. Dans le champSecret, collez votre jeton d'accès personnel GitHub. Remplissez le champDescription afin de pouvoir identifier cette entrée à une date ultérieure. Vous pouvez laisser le champ Scope as Global et le champ ID vide:
Cliquez sur le boutonOK lorsque vous avez terminé.
Vous pourrez maintenant référencer ces informations d’identification à partir d’autres parties de Jenkins pour faciliter la configuration.
Configurer l'accès Jenkins à GitHub
De retour dans le tableau de bord principal de Jenkins, cliquez surManage Jenkins dans le menu de gauche:
Dans la liste des liens de la page suivante, cliquez surConfigure System:
Faites défiler les options de la page suivante jusqu'à ce que vous trouviez la sectionGitHub. Cliquez sur le boutonAdd GitHub Server puis sélectionnezGitHub Server:
La section se développera pour demander des informations supplémentaires. Dans le menu déroulantCredentials, sélectionnez votre jeton d'accès personnel GitHub que vous avez ajouté dans la dernière section:
Cliquez sur le boutonTest connection. Jenkins effectuera un appel API de test sur votre compte et vérifiera la connectivité:
Lorsque vous avez terminé, cliquez sur le boutonSave pour appliquer vos modifications.
Configurer l'application de démonstration dans votre compte GitHub
Pour montrer comment utiliser Jenkins pour tester une application, nous utiliserons un simple“hello world” program créé avecHapi.js. Comme nous configurons Jenkins pour réagir aux envois dans le référentiel, vous devez disposer de votre propre copie du code de démonstration.
Visitez leproject repository et cliquez sur le boutonFork dans le coin supérieur droit pour faire une copie du référentiel dans votre compte:
Une copie du référentiel sera ajoutée à votre compte.
Le référentiel contient un fichierpackage.json
qui définit les dépendances d'exécution et de développement, ainsi que la manière d'exécuter la suite de tests incluse. Les dépendances peuvent être installées en exécutantnpm install
et les tests peuvent être exécutés en utilisantnpm test
.
Nous avons également ajouté unJenkinsfile
au repo. Jenkins lit ce fichier pour déterminer les actions à exécuter sur le référentiel à construire, à tester ou à déployer. Il est écrit en utilisant la version déclarative des JenkinsPipeline DSL.
LeJenkinsfile
inclus dans le référentielhello-hapi
ressemble à ceci:
Jenkinsfile
#!/usr/bin/env groovy
pipeline {
agent {
docker {
image 'node'
args '-u root'
}
}
stages {
stage('Build') {
steps {
echo 'Building...'
sh 'npm install'
}
}
stage('Test') {
steps {
echo 'Testing...'
sh 'npm test'
}
}
}
}
Lepipeline
contient la définition entière que Jenkins évaluera. À l'intérieur, nous avons une sectionagent
qui spécifie où les actions dans le pipeline seront exécutées. Pour isoler nos environnements du système hôte, nous allons tester dans des conteneurs Docker, spécifiés par l'agentdocker
.
Puisque Hapi.js est un framework pour Node.js, nous utiliserons l'image Docker denode
comme base. Nous spécifions l'utilisateurroot
dans le conteneur afin que l'utilisateur puisse simultanément écrire à la fois sur le volume attaché contenant le code extrait et sur le volume sur lequel le script écrit sa sortie.
Ensuite, le fichier définit deux étapes, qui ne sont que des divisions logiques du travail. Nous avons nommé le premier “Build” et le second “Test”. L'étape de construction imprime un message de diagnostic, puis exécutenpm install
pour obtenir les dépendances requises. L'étape de test imprime un autre message, puis exécutez les tests tels que définis dans le fichierpackage.json
.
Maintenant que vous avez un référentiel avec unJenkinsfile
valide, nous pouvons configurer Jenkins pour surveiller ce référentiel et exécuter le fichier lorsque des modifications sont apportées.
Créer un nouveau pipeline dans Jenkins
Ensuite, nous pouvons configurer Jenkins pour qu’il utilise le jeton d’accès personnel GitHub pour surveiller notre référentiel.
De retour dans le tableau de bord principal de Jenkins, cliquez surNew Item dans le menu de gauche:
Entrez un nom pour votre nouveau pipeline dans le champEnter an item name. Ensuite, sélectionnezPipeline comme type d'élément:
Cliquez sur le boutonOK en bas pour continuer.
Sur l'écran suivant, cochez la caseGitHub project. Dans le champProject url qui apparaît, saisissez l'URL du référentiel GitHub de votre projet.
[.note] #Note: Assurez-vous de pointer vers votre fork de l'application Hello Hapi afin que Jenkins ait l'autorisation de configurer les webhooks.
#
Ensuite, dans la sectionBuild Triggers, cochez la caseGitHub hook trigger for GITScm polling:
Dans la sectionPipeline, nous devons dire à Jenkins d'exécuter le pipeline défini dans lesJenkinsfile
de notre référentiel. Changez le type deDefinition enPipeline script from SCM.
Dans la nouvelle section qui apparaît, choisissezGit dans le menuSCM. Dans le champRepository URL qui apparaît, saisissez à nouveau l'URL de votre fork du référentiel:
[.note] #Note: Encore une fois, assurez-vous de pointer vers votre fork de l'application Hello Hapi.
#
[.note] #Note: Notre exemple fait référence à unJenkinsfile
disponible dans un référentiel public. Si votre projet n'est pas accessible publiquement, vous devrez utiliser le boutonadd credentials pour ajouter un accès supplémentaire au référentiel. Vous pouvez ajouter un jeton d'accès personnel comme nous l'avons fait avec la configuration des hooks précédemment.
#
Lorsque vous avez terminé, cliquez sur le boutonSave en bas de la page.
Effectuer une construction initiale et configurer les Webhooks
Au moment de la rédaction de cet article (juin 2017), Jenkins ne configure pas automatiquement les WebHooks lorsque vous définissez le pipeline du référentiel dans l'interface.
Pour que Jenkins configure les hooks appropriés, nous devons effectuer une construction manuelle la première fois.
Sur la page principale de votre pipeline, cliquez surBuild Now dans le menu de gauche:
Une nouvelle construction sera programmée. Dans la caseBuild History dans le coin inférieur gauche, une nouvelle construction devrait apparaître dans un instant. De plus, unStage View commencera à être dessiné dans la zone principale de l'interface. Cela permettra de suivre la progression de votre test au fur et à mesure que les différentes étapes sont complétées:
Dans la caseBuild History, cliquez sur le numéro associé à la construction pour accéder à la page de détail de la construction. De là, vous pouvez cliquer sur le boutonConsole Output dans le menu de gauche pour voir les détails des étapes qui ont été exécutées:
Cliquez sur l'élémentBack to Project dans le menu de gauche lorsque vous avez terminé afin de revenir à la vue principale du pipeline.
Maintenant que le projet a été construit une fois, Jenkins peut créer les liens Web pour notre projet. Cliquez surConfigure dans le menu de gauche du pipeline:
Aucune modification n'est nécessaire sur cet écran, cliquez simplement sur le boutonSave en bas. Maintenant que Jenkins a des informations sur le projet depuis le processus de construction initial, il va enregistrer un Webhook avec notre projet GitHub lorsque vous enregistrez la page.
Vous pouvez vérifier cela en accédant à votre référentiel GitHub et en cliquant sur le boutonSettings. Sur la page suivante, cliquez surWebhooks dans le menu latéral. Vous devriez voir votre Webhook de serveur Jenkins dans l'interface principale:
Maintenant, lorsque vous insérez de nouvelles modifications dans votre référentiel, Jenkins en sera informé. Il extrait ensuite le nouveau code et le teste à nouveau en suivant la même procédure.
Pour se rapprocher de cela, dans notre page de référentiel sur GitHub, vous pouvez cliquer sur le boutonCreate new file à gauche du bouton vertClone or download:
Sur la page suivante, choisissez un nom de fichier et un contenu factice:
Cliquez sur le boutonCommit new file en bas lorsque vous avez terminé.
Si vous revenez à votre interface Jenkins, vous verrez une nouvelle construction automatiquement démarrée:
Vous pouvez lancer des builds supplémentaires en effectuant des commits sur une copie locale du référentiel et en le renvoyant à GitHub.
Conclusion
Dans ce guide, nous avons configuré Jenkins pour surveiller un projet GitHub et tester automatiquement toutes les nouvelles modifications validées. Jenkins extrait le code du référentiel, puis exécute les procédures de construction et de test à partir de conteneurs Docker isolés. Le code résultant peut être déployé ou stocké en ajoutant des instructions supplémentaires aux mêmesJenkinsfile
.