Comment configurer des pipelines d'intégration continue (CI) GitLab sur Ubuntu 20.04

Chaque développeur comprend à quel point le contrôle de version est crucial pour le cycle de vie du développement logiciel. Il permet à plusieurs personnes de travailler simultanément sur un seul projet, chaque personne conservant sa propre copie du code et choisissant quand la partager avec le reste de l'équipe. Pour y parvenir, les développeurs utilisent des Git dépôts pour faciliter le contrôle de version. GitLab est un dépôt Git basé sur le web qui est bien plus qu'un simple outil de contrôle de version. Il fournit également des outils DevOps, un suivi des tickets, de l'intégration continue et du déploiement.

GitLab propose trois options au choix : GitLab Community Edition (CE), GitLab Enterprise Edition (EE) et GitLab SaaS. GitLab CE and GitLab EE sont des solutions auto-hébergées. Cela signifie que vous devez télécharger, installer et gérer vous-même l'instance GitLab. GitLab SaaS est hébergé par GitLab Inc. Ainsi, vous n'avez pas à vous soucier d'installer quoi que ce soit pour l'utiliser. Il vous suffit de créer un compte GitLab et de commencer.

Dans ce tutoriel, nous allons vous montrer comment configurer des pipelines d'intégration continue avec GitLab CI pour surveiller les modifications de vos dépôts et exécuter des tests automatisés afin de valider le nouveau code. Nous commencerons par configurer un dépôt Git pour héberger le code. Ensuite, nous configurerons un processus CI pour surveiller les commits sur le dépôt et lancerons un runner CI pour exécuter les tests dans un conteneur Docker isolé.

Prérequis

Pour commencer, vous aurez besoin d'un serveur exécutant le logiciel de contrôle de version GitLab. GitLab auto-hébergé et GitLab SaaS peuvent tous deux exécuter des tests automatisés. Cependant, il existe certaines limites en termes de minutes et de ressources mises à disposition pour vos tests dans les options SaaS gratuites. Vous disposez de plus de liberté si vous utilisez les options auto-hébergées, car vous pouvez allouer autant de ressources que vous le souhaitez à votre instance GitLab. Suivez notre tutoriel sur l'hébergement de vos propres dépôts Git avec GitLab pour apprendre à configurer votre propre instance GitLab.

Vous aurez besoin d'au moins un serveur à utiliser comme runner GitLab CI. Cependant, si vous le souhaitez, vous pouvez également avoir plusieurs serveurs. Si vous avez configuré une instance GitLab auto-hébergée, vous pouvez utiliser le même serveur, mais nous préférons configurer un serveur différent pour le runner CI. Ce tutoriel sur Comment configurer votre serveur Ubuntu est un bon point de départ.

Vous devrez installer Docker sur vos serveurs de runner GitLab CI afin d'isoler les environnements de test dans des conteneurs Docker. Nous avons un tutoriel sur Comment installer et utiliser Docker sur Ubuntu qui peut vous aider à remplir cette condition.

Maintenant que nous avons tout ce dont nous avons besoin, commençons !

Étape 1 : Créer un projet sur une instance GitLab

Nous allons commencer par créer un dépôt de projet sur GitLab. Nous allons baser ce tutoriel sur une application Node.js. Comme nous ne voulons pas créer les fichiers du projet à partir de zéro, GitLab propose un outil pour importer des projets depuis d'autres dépôts de contrôle de version que nous allons utiliser. L'application que nous importons est une simple application “hello world” construite avec Express.js – un framework web minimaliste pour les applications Node.js. Nous allons implémenter les tests en utilisant Mocha et Chai – ce sont des frameworks JavaScript utilisés pour les tests unitaires. Mocha permet des tests asynchrones, des rapports de couverture de test, et peut être associé à d'autres bibliothèques d'assertion. Chai est une bibliothèque d'assertion. Elle peut être associée à n'importe quel framework de test, dans notre cas, nous associerons Mocha à Chai.

Now that you know the basics of our project, log in to your GitLab instance (whether self-managed or SaaS), click on the ‘plus’ de la barre de navigation supérieure, et sélectionnez ‘Nouveau projet’. Facultativement, si vous faites défiler vers le haut de la page d'accueil de votre compte, vous pouvez cliquer sur le bouton ‘Nouveau projet’ :

Sur la page du nouveau projet, cliquez sur l'onglet Importer un projet :

Ensuite, dans la page qui s'ouvre, cliquez sur le bouton Dépôt par URL :

Bien qu'il existe une option d'importation depuis GitHub, nous ne l'utiliserons pas car elle nécessite un jeton d'accès personnel (Personal access token). Nous n'avons pas besoin de configurer de jetons d'accès personnels puisque nous travaillons avec un dépôt public, et l'importation uniquement avec l'URL est simple.

Après cela, copiez l'URL suivante et collez-la dans le champ URL du dépôt Git :

Cela devrait ressembler à ceci :

Laissez le dépôt en tant que Privé et cliquez sur le bouton Créer un projet lorsque vous avez terminé. Attendez quelques secondes que le projet soit importé depuis GitHub et il apparaîtra parmi vos dépôts GitLab. GitLab importe le projet avec les mêmes détails que le projet du dépôt GitHub.

Étape 2 : Analyse du fichier .gitlab-ci.yml

GitLab CI parcourt chaque dépôt sur GitLab à la recherche d'un fichier nommé .gitlab-ci.yml pour savoir comment exécuter les tests automatisés. Dans le dépôt que nous venons d'importer, vous pouvez voir un fichier .gitlab-ci.yml parmi les fichiers du projet. Vous trouverez plus d'informations sur le fichier yml de GitLab CI dans leur documentation officielle de référence des mots-clés pour le fichier .gitlab-ci.yml.

Dans l'interface du dépôt GitLab, cliquez sur le fichier .gitlab-ci.yml pour l'ouvrir dans la page du navigateur. Cela devrait ressembler à ceci :

Notez l'indentation des lignes. Le fichier suit une GitLab CI YAML syntaxe de configuration stricte pour définir les différentes actions à entreprendre, dans un ordre spécifié sous certaines conditions. Pour vous assurer que vos fichiers de configuration sont corrects, GitLab fournit un utilitaire de test pour la validation. Dans votre instance GitLab, dans le dépôt de votre projet, vous pouvez visiter l'interface CI lint pour valider votre .gitlab-ci.yml. Cliquez sur CI/CD dans le menu de navigation de gauche, puis cliquez sur le bouton CI lint dans la page qui s'affiche :

Les directives du fichier de configuration sont présentées ci-dessous.

• Image Docker de base

La première ligne du fichier de configuration déclare une image Docker qui doit être utilisée pour exécuter les tests. Comme nous construisons une application Node.js, nous choisissons la dernière image Node.js :

• Stages

Ensuite, nous définissons les différentes étapes par lesquelles nous voulons que nos tests d'intégration continue passent. Nous n'avons que deux étapes :

Lors de la définition des noms d'étapes, les noms comme build ou test sont choisis au hasard – vous pouvez choisir le nom que vous voulez. Cependant, vous devez ordonner les étapes correctement car cela détermine le flux d'exécution. Dans notre cas, les tâches de l'étape build s'exécutent avant les tâches de l'étape test . Le runner GitLab exécutera les tâches d'une même étape en parallèle et attendra que toutes les tâches soient terminées avant de commencer à exécuter les tâches de l'étape suivante.

• Cache

Une cache définition est incluse pour spécifier les fichiers et répertoires qui seront mis en cache ou enregistrés pour une utilisation ultérieure entre les exécutions de tâches :

Définir la mise en cache permet de minimiser le temps nécessaire à l'exécution des tâches qui dépendent de ressources peu susceptibles de changer entre les exécutions. Nous spécifions le répertoire node_modules à mettre en cache. C'est le répertoire dans lequel npm installe les dépendances du projet.

• Jobs

Nous avons deux tâches dans la configuration :

• install_dependencies

Lors du nommage des tâches, vous êtes libre de choisir n'importe quel nom. Cependant, il est recommandé de choisir un nom descriptif car ils sont utilisés dans l'interface utilisateur de GitLab – cela peut être utile lors du débogage. Vous trouverez la plupart des configurations sur le web combinant npm install avec les commandes de l'étape de test. Nous les avons seulement séparés pour aider à démontrer comment les jobs interagissent car il s'agit d'un projet assez petit. Le stage directive marque ce job comme build – il est exécuté dans le stage.

La directive script spécifie les commandes à exécuter lors de l'exécution de ce job. Vous pouvez spécifier plusieurs commandes en ajoutant des lignes dans le bloc script . Bien sûr, vous devez veiller à respecter l'indentation et à garder à l'esprit l'ordre dans lequel les scripts doivent être exécutés.

La directive artifacts spécifie les fichiers ou les chemins de répertoires à sauvegarder et à partager entre les étapes. À nouveau, rappelons qu'ordonner correctement les étapes est crucial pour s'assurer que les autres fichiers auront ce dont ils ont besoin pour s'exécuter. La commande npm install installera les dépendances dans le répertoire node_modules . En la déclarant dans les artifacts, nous la rendons disponible pour les jobs exécutés dans les étapes suivantes. Les fichiers sont également rendus disponibles dans l'interface utilisateur de GitLab si vous souhaitez les télécharger.

• test_with_mocha

Ce job est exécuté sur l'étape test . Comme ce job s'exécute après celui de l'étape build , les artifacts déclarés dans l'étape build (qui sont les dépendances de notre application) seront disponibles pour l'étape test . Le bloc script spécifie les commandes npm pour exécuter nos tests. Nous démarrons d'abord notre application, puis nous exécutons les tests sur celle-ci. L'exécution de ces commandes lance les commandes spécifiées dans la section du bloc de script de package.json :
Avec cela, vous devriez avoir une compréhension de base du fichier .gitlab-ci.yml . Nous disons de base car il ne s'agit que d'une application statique hello world . Ensuite, voyons comment nous pouvons déclencher une nouvelle exécution de CI.

Step 3: Triggering a GitLab CI Run

Vous serez ravi d'apprendre qu'une fois que votre dépôt contient le fichier .gitlab-ci.yml , tous les nouveaux commits que vous y pousserez déclencheront une nouvelle exécution d'intégration continue. Dans le cas des instances GitLab auto-gérées, si vous n'avez pas configuré de GitLab runner, l'exécution de la CI sera mise en attente (« pending »).

GitLab SaaS fournit aux utilisateurs des runners partagés qui peuvent prendre en charge leurs jobs et les exécuter automatiquement. Cela n'est possible que si les runners partagés sont libres et que vous n'avez pas dépassé votre quota. Dans GitLab SaaS, vous pouvez choisir si vous souhaitez que votre dépôt utilise les shared runners ou non en vous rendant sur la page Settings > CI / CD de votre projet, comme le montre la capture d'écran ci-dessous. Sur cette page, vous trouverez également des informations sur les instructions d'installation du GitLab runner, que nous approfondirons à l'étape suivante :

Now, let’s make a small change to trigger a CI run. Navigate back into your node_pipeline dépôt de projet GitLab :

Click on the README.md mis en évidence ci-dessus pour l'afficher :

Click on the ‘Edit’ pour ouvrir le fichier en édition dans le navigateur, et ajoutez du texte :

Once you have added some text, scroll down and click the Commit changes pour enregistrer les modifications. Vous pouvez modifier le message de commit comme vous le souhaitez. Il apparaîtra comme titre dans l'interface utilisateur de GitLab lorsque le pipeline sera en cours d'exécution. Nous l'avons laissé sous la forme Update README.md car c'est assez descriptif :

Once you have committed the changes, return to the main project page. You will notice a small paused icon associée au commit le plus récent. Si vous passez votre souris sur l'icône, elle affichera : ‘Pipeline:pending’:

Cela signifie que l'exécution de la CI a été déclenchée. Cependant, les tests n'ont pas encore été exécutés. Dans le menu de navigation de gauche, cliquez sur CI/CD, puis sélectionnez Pipelines. Cela ouvrira une page affichant plus de détails sur le pipeline. Vous pouvez voir que la CI est en attente et marquée comme bloquée :

To get more details about the run, click on the pending . Vous verrez la vue ci-dessous, affichant les différentes étapes de l'exécution et les jobs individuels liés à chaque étape :

Vous pouvez également cliquer sur des jobs individuels pour voir leurs détails plus précis, comme ce qui cause les retards. Dans le cas d'exécutions échouées, c'est ici que vous verrez ce qui a causé l'échec du job :

Le message indique que le job est bloqué parce que vous n'avez configuré aucun runner actif capable de l'exécuter. Nous ferons cela à l'étape suivante. Lorsque vous rendrez un runner disponible, le job commencera à s'exécuter automatiquement. Lorsqu'un job s'exécute, vous verrez la sortie sur cette interface ainsi que les autres artefacts téléchargeables générés lors de l'exécution du job.

Étape 4 : Configuration d'un service de runner GitLab CI

Il est maintenant temps d'utiliser le deuxième serveur que nous avons déclaré dans la section Prérequis de ce tutoriel. Nous allons installer et configurer un service de runner GitLab sur ce serveur. Vous pouvez déployer le service pour exécuter plusieurs instances de runner pour différents projets sur GitLab.

Vous avez la possibilité de déployer le runner sur le même serveur que celui qui héberge votre instance GitLab auto-gérée. Cependant, pour s'assurer qu'une instance n'est pas limitée par les ressources, il est préférable de configurer une instance de runner CI distincte. Quelle que soit la configuration choisie, Docker doit être installé pour isoler les environnements de test.

Le processus d'installation du runner GitLab CI est comparable à celui de l'installation de l'instance GitLab auto-gérée . Nous commençons par télécharger un script pour ajouter le dépôt officiel de GitLab aux sources apt en utilisant la commande suivante :

Saisissez votre mot de passe root lorsque vous y êtes invité. Ensuite, vous pouvez maintenant exécuter la commande pour installer le dernier runner GitLab CI :

La commande ci-dessus installe et enregistre un service de runner prêt à être utilisé par vos projets.

Étape 5 : Obtention des jetons d'enregistrement et liaison du runner GitLab

Pour configurer un runner GitLab CI afin qu'il commence à accepter des jobs, vous avez besoin d'un jeton de runner GitLab. Il est nécessaire pour que le runner s'authentifie auprès de votre instance de serveur GitLab. Il existe deux types de jetons selon la façon dont vous souhaitez utiliser le runner : spécifique au projet et runner partagé.

Les runners spécifiques au projet sont applicables si vous avez des exigences uniques pour le runner. Par exemple, si vous avez des définitions de déploiement dans votre gitlab-ci.yml avec des jetons uniques, un runner spécifique peut être recommandé pour s'authentifier correctement dans l'environnement de déploiement. Une autre considération est de savoir si vos étapes d'intégration continue comportent des processus gourmands en ressources. Dans ce cas, il serait idéal d'opter pour un runner spécifique au projet. Notez qu'un runner spécifique au projet n'accepte pas les jobs d'autres projets.

Les runners partagés sont à usage général et peuvent être utilisés par plusieurs projets. L'instance SaaS de GitLab hébergée sur GitLab Inc dispose de runners partagés qui prendront automatiquement en charge vos pipelines comme expliqué à l' Étape trois. Les runners récupèrent les jobs de vos configurations en fonction d'un algorithme qui prend en compte le nombre de jobs en cours d'exécution pour chaque projet. Un runner partagé est plus flexible qu'un runner spécifique. Il peut être configuré depuis le compte administrateur de l'instance GitLab. Voyons comment obtenir les jetons pour les deux runners.

• Enregistrer un runner spécifique au projet

Pour enregistrer un runner spécifique au projet, ouvrez votre projet dans votre instance GitLab ou votre compte GitLab SaaS. Dans le menu de navigation de gauche, cliquez sur l'élément Paramètres et sélectionnez l'option CI/CD :

Après cela, faites défiler vers le bas jusqu'à la section Runners et cliquez sur le bouton pour développer la section :

Le côté gauche explique comment enregistrer un runner spécifique au projet. Il s'agit d'une vue de l'instance SaaS de GitLab. Vous pouvez également configurer des runners automatiques avec Kubernetes, mais nous utilisons le runner manuel pour ce tutoriel :

Ensuite, vous devez vous concentrer sur la section où le jeton pour ce projet vous est fourni. Pour une instance GitLab auto-hébergée, l'URL affichera le domaine du serveur sur lequel votre instance GitLab s'exécute :

Vous pouvez choisir de désactiver les runners partagés pour ce projet en basculant l'interrupteur dans la section de droite sous Runners partagés. Ensuite, copiez le jeton d'enregistrement affiché dans votre bloc-notes, car nous l'utiliserons plus tard.

• Enregistrer un runner partagé

Pour enregistrer un runner partagé, vous devez vous connecter à votre instance GitLab auto-hébergée en tant qu'administrateur. Pour accéder au panneau d'administration, cliquez sur l'icône de clé à molette/clé plate dans le menu de navigation supérieur :

Dans le Panneau d'administration, cliquez sur Runners dans la section Vue d'ensemble du menu de gauche. Cela ouvrira une page contenant les instructions de configuration des Runners partagés :

Copiez le jeton d'enregistrement affiché sur le côté droit sous Configurer un Runner partagé manuellement. Vous utiliserez ce jeton pour enregistrer le runner à l'étape suivante.

• Lier un GitLab CI Runner à une instance GitLab

Dans cette étape, vous allez lier votre instance GitLab au runner CI. Reconnectez-vous au serveur sur lequel vous avez installé le service GitLab runner à l' Étape quatre. Pour démarrer le processus d'enregistrement du runner, saisissez la commande suivante dans votre terminal :

La commande vous pose une série de questions :

• Saisissez l'URL de l'instance GitLab (par exemple, https://gitlab.com/) :

Fournissez le nom de domaine de votre instance GitLab en utilisant https:// pour spécifier le protocole SSL.

• Saisissez le jeton d'enregistrement :

Fournissez votre jeton d'enregistrement. C'est ici que vous choisirez si vous souhaitez que ce runner soit spécifique à un projet ou partagé. Vous ne pouvez fournir qu'un seul des jetons que vous avez copiés précédemment pour l'une ou l'autre des options.

• Saisissez une description pour le runner :

Choisissez un nom descriptif pour votre runner CI tel qu'il apparaîtra dans l'interface utilisateur de l'instance GitLab.

• Saisissez un exécuteur : custom, docker-ssh, parallels, virtualbox, docker, shell, ssh, docker+machine, docker-ssh+machine, kubernetes :

Ici, des options vous sont proposées pour choisir un exécuteur afin d'exécuter les tâches. Saisissez Docker.

• Saisissez les tags pour le runner (séparés par des virgules) :

Ceci est facultatif. Vous pouvez saisir des noms de tags tels que les dépendances incluses dans ce runner. Vous pouvez laisser ce champ vide pour l'instant.

• Saisissez l'image Docker par défaut (par exemple, ruby:2.6) :

Ici, vous devez spécifier une image d'usage général par défaut utilisée pour exécuter les tâches au cas où le fichier gitlab-ci.yml ne spécifie pas d'image. Saisissez alpine:latest car il s'agit d'une image petite, polyvalente et sécurisée. Appuyez sur Entrée et le runner sera enregistré et démarré automatiquement :

Pour afficher la liste des runners actuellement disponibles, saisissez la commande suivante :

Étape 6 : Confirmer que le CI Runner est correctement lié dans GitLab

Ensuite, retournez sur votre navigateur et visitez la page de votre projet dans l'instance GitLab. Selon le nombre de minutes écoulées depuis l'enregistrement du runner, vous verrez peut-être que la tâche est en cours d'exécution :

Ou elle peut être terminée :

Après cela, accédez à la page Pipelines soit via le menu de gauche CI/CD > Pipelines, soit en cliquant sur l'icône en cours, réussi, ou échoué (si le pipeline a rencontré des erreurs) pour voir l'état de l'exécution du CI. Ici, nous pouvons voir que l'une des étapes (étape de build) a réussi, tandis qu'une autre est toujours en cours :

Dans le tableau, sous l'en-tête Étapes, cliquez sur l'une des icônes d'étape pour afficher les tâches associées :

Ensuite, cliquez sur une tâche dans la fenêtre contextuelle pour afficher les détails :

La tâche s'est exécutée et vous pouvez voir la progression lorsque la commande npm installait les dépendances. Sur le côté droit, vous pouvez voir d'autres informations connexes. Vous avez la possibilité de télécharger les artefacts de la tâche. Vous pouvez également basculer entre les étapes pour afficher d'autres tâches à partir du menu déroulant.

Ici, vous pouvez voir nos cas de test s'afficher lorsque vous sélectionnez la tâche dans l'étape de test :

Runners disponibles

Dans le menu de gauche, si vous cliquez sur Paramètres > CI/CD, et développez la section Runners , vous devriez voir le runner que vous venez d'enregistrer. Selon que vous avez spécifié un jeton spécifique au projet ou un jeton partagé, le runner apparaîtra dans la section correspondante.

Ici, vous pouvez voir que nous avons enregistré un jeton spécifique au projet. Le runner apparaît sous Runners spécifiques:

Conclusion

Dans ce tutoriel, vous avez appris comment automatiser vos tests avec GitLab CI. Nous avons commencé par configurer un projet d'application Node.js sur GitLab. Le projet comprenait des cas de test et un gitlab-ci.yml. Nous avons appris que GitLab utilise le gitlab-ci.yml fichier pour déterminer ce qu'il doit faire lorsqu'il est déclenché. Un gitlab-ci.yml fichier est simplement un fichier de configuration qui contient des instructions sur la construction et le test d'applications, écrit au YAML format qu'un runner GitLab CI peut comprendre.

Nous avons également réussi à configurer un runner GitLab CI sur un hôte distinct. Nous l'avons enregistré pour qu'il récupère les tâches de nos instances GitLab chaque fois qu'il y a un déclencheur. Bien qu'il s'agisse d'un projet simple, vous pouvez vous appuyer sur ces informations pour configurer des pipelines pour des projets complexes. Les étapes pour ajouter un projet à GitLab et lier un runner GitLab CI restent les mêmes. Les seules choses qui changent sont les instructions et les étapes dans le gitlab-ci.yml fichier.

Bon développement !