Comment configurer des pipelines d’intégration continue avec GitLab CI sur Ubuntu 16.04

introduction

GitLab Community Edition est un fournisseur de référentiels Git auto-hébergé doté de fonctionnalités supplémentaires facilitant la gestion de projets et le développement de logiciels. L’une des fonctionnalités les plus précieuses offertes par GitLab est l’outil intégré d’intégration et de distribution continue appelé GitLab CI.

Dans ce guide, nous montrerons comment configurer GitLab CI pour surveiller les modifications apportées à votre référentiel et exécuter des tests automatisés pour valider le nouveau code. Nous allons commencer par une installation GitLab en cours d’exécution dans laquelle nous allons copier un exemple de référentiel pour une application de base Node.js. Après la configuration de notre processus CI, lorsqu’un nouveau commit est poussé dans le référentiel, GitLab utilisera CI Runner pour exécuter la suite de tests par rapport au code contenu dans un conteneur Docker isolé.

Conditions préalables

Avant de commencer, vous devez configurer un environnement initial. Nous avons besoin d’un serveur GitLab sécurisé configuré pour stocker notre code et gérer nos processus CI / CD. De plus, nous avons besoin d’un emplacement pour exécuter les tests automatisés. Cela peut être soit le même serveur sur lequel GitLab est installé, soit un hôte séparé. Les sections ci-dessous couvrent les exigences plus en détail.

Un serveur GitLab sécurisé avec SSL

Pour stocker le code source et configurer nos tâches CI / CD, nous avons besoin d’une instance de GitLab installée sur un serveur Ubuntu 16.04. GitLab recommande actuellement un serveur avec au moins * 2 cœurs de processeur * et * 4 Go de RAM *. Pour éviter que votre code soit exposé ou altéré, l’instance GitLab sera protégée avec SSL à l’aide de Let’s Encrypt. Votre serveur doit être associé à un nom de domaine ou à un sous-domaine pour pouvoir effectuer cette étape.

Vous pouvez compléter ces exigences à l’aide des didacticiels suivants:

Utilisation initiale du serveur avec Ubuntu 16.04: Créez un utilisateur + sudo + et configurez un pare-feu de base
Comment installer et configurer GitLab sur Ubuntu 16.04: Installez GitLab sur le serveur et le protéger avec un certificat Let’s Encrypt TLS / SSL

Nous montrerons comment partager des coureurs CI / CD (les composants qui exécutent les tests automatisés) entre projets et comment les verrouiller à des projets uniques. Si vous souhaitez partager des coureurs CI entre projets, nous vous recommandons vivement de limiter ou de désactiver les inscriptions publiques. Si vous n’avez pas modifié vos paramètres lors de l’installation, revenez en arrière et suivez https://www.digitalocean.com/community/tutorials/how-to-install-and-configure-gitlab-on-ubuntu-16-04#restrict -or-disable-public-up-ups- (facultatif) [étape facultative de l’article d’installation de GitLab sur la restriction ou la désactivation des inscriptions] afin de prévenir les abus commis par des tiers.

Un ou plusieurs serveurs à utiliser en tant que coureurs GitLab CI

Les GitLab CI Runners sont les serveurs qui extraient le code et exécutent des tests automatisés pour valider les nouvelles modifications. Pour isoler l’environnement de test, nous allons exécuter tous nos tests automatisés dans des conteneurs Docker. Pour ce faire, nous devons installer Docker sur le ou les serveurs qui exécuteront les tests.

Cette étape peut être effectuée sur le serveur GitLab ou sur un autre serveur Ubuntu 16.04 pour fournir une isolation supplémentaire et éviter les conflits de ressources. Les tutoriels suivants installeront Docker sur l’hôte que vous souhaitez utiliser pour exécuter vos tests:

Initial Initial Server Server Setup with Ubuntu 16.04: Créez un utilisateur + sudo + et configurez un pare-feu de base (vous ne devez pas compléter cette opération si vous configurez le coureur de CI sur le serveur GitLab)
Comment installer et utiliser Docker sur Ubuntu 16.04: Suivez * les étapes 1 et 2 * pour installer Docker sur le serveur

Lorsque vous êtes prêt à commencer, continuez avec ce guide.

Copier le référentiel d’exemples à partir de GitHub

Pour commencer, nous allons créer un nouveau projet dans GitLab contenant l’exemple d’application Node.js. Nous allons importer le référentiel original directement à partir de GitHub afin que nous n’ayons pas à le télécharger manuellement.

Connectez-vous à GitLab et cliquez sur l’icône * plus * dans le coin supérieur droit et sélectionnez * Nouveau projet * pour ajouter un nouveau projet:

image: https: //assets.digitalocean.com/articles/gitlab_ci_usage/new_project_icon_3.png [GitLab ajoute une nouvelle icône de projet]

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

image: https: //assets.digitalocean.com/articles/gitlab_ci_usage/import-project.png [nouveau nom du projet GitLab]

Ensuite, cliquez sur le bouton * Repo par URL *. Bien qu’il existe une option d’importation GitHub, elle nécessite un jeton d’accès personnel et permet d’importer le référentiel et des informations supplémentaires. Nous ne nous intéressons qu’au code et à l’historique Git, ce qui facilite l’importation par URL.

Dans le champ * URL du référentiel Git *, entrez l’URL du référentiel GitHub suivante:

https://github.com/do-community/hello_hapi.git

Ça devrait ressembler à ça:

image: https: //assets.digitalocean.com/articles/gitlab_ci_usage/new_project_github_url2.png [nouvelle URL GitHub du projet GitLab]

Comme il s’agit d’une démonstration, il est probablement préférable de garder le référentiel marqué * Privé *. Lorsque vous avez terminé, cliquez sur * Créer un projet *.

Le nouveau projet sera créé sur la base du référentiel importé de GitHub.

Comprendre le fichier .gitlab-ci.yml

GitLab CI recherche un fichier nommé + .gitlab-ci.yml + dans chaque référentiel afin de déterminer comment il convient de tester le code. Le référentiel que nous avons importé contient un fichier + gitlab-ci.yml + déjà configuré pour le projet. Vous pouvez en apprendre plus sur le format en lisant la .gitlab-ci.yml documentation de référence

Cliquez sur le fichier + .gitlab-ci.yml + dans l’interface GitLab pour le projet que nous venons de créer. La configuration du CI devrait ressembler à ceci:

gitlab-ci.yml

image: node:latest

stages:
 - build
 - test

cache:
 paths:
   - node_modules/

install_dependencies:
 stage: build
 script:
   - npm install
 artifacts:
   paths:
     - node_modules/

test_with_lab:
 stage: test
 script: npm test

Le fichier utilise la GitLab Syntaxe de configuration CI YAML pour définir les actions à entreprendre, leur ordre d’exécution, les conditions dans lesquelles elles doivent être exécutées. et les ressources nécessaires pour effectuer chaque tâche. Lors de l’écriture de vos propres fichiers CI GitLab, vous pouvez visiter une syntaxe linter en accédant à + / ci / lint + dans votre instance GitLab pour valider que votre fichier est correctement formaté.

Le fichier de configuration commence par déclarer un Docker + image + qui devrait être utilisé pour exécuter la suite de tests. Hapi étant un framework Node.js, nous utilisons la dernière image Node.js:

image: node:latest

Ensuite, nous définissons explicitement différentes étapes d’intégration continue qui seront exécutées:

stages:
 - build
 - test

Les noms que vous choisissez ici sont arbitraires, mais l’ordre détermine l’ordre d’exécution des étapes à suivre. Les étapes sont des balises que vous pouvez appliquer à des travaux individuels. GitLab exécutera les travaux de la même étape en parallèle et attendra l’exécution de la prochaine étape jusqu’à ce que tous les travaux de l’étape en cours soient terminés. Si aucune étape n’est définie, GitLab utilisera trois étapes appelées + build,` + test` et + deploy et affectera tous les travaux à l’étape` + test + `par défaut.

Après avoir défini les étapes, la configuration inclut une définition + cache +:

cache:
 paths:
   - node_modules/

Cela spécifie les fichiers ou les répertoires pouvant être mis en cache (enregistrés pour une utilisation ultérieure) entre les exécutions ou les étapes. Cela peut aider à réduire le temps nécessaire à l’exécution de travaux reposant sur des ressources susceptibles de ne pas changer entre les exécutions. Ici, nous mettons en cache le répertoire + node_modules +, qui est où + npm + installera les dépendances qu’il télécharge.

Notre premier travail s’appelle + install_dependencies +:

install_dependencies:
 stage: build
 script:
   - npm install
 artifacts:
   paths:
     - node_modules/

Les travaux peuvent porter n’importe quel nom, mais comme les noms sont utilisés dans l’interface utilisateur de GitLab, les noms descriptifs sont utiles. Habituellement, + npm install peut être combiné aux étapes de test suivantes, mais pour mieux démontrer l’interaction entre les étapes, nous extrayons cette étape pour qu’elle se déroule dans sa propre étape.

Nous marquons explicitement l’étape comme “build” avec la directive + stage +. Ensuite, nous spécifions les commandes à exécuter à l’aide de la directive + script +. Vous pouvez inclure plusieurs commandes en ajoutant des lignes supplémentaires dans la section + script +.

La sous-section + artefacts + sert à spécifier les chemins de fichier ou de répertoire à enregistrer et à passer entre les étapes. Comme la commande + npm install + installe les dépendances du projet, notre prochaine étape devra avoir accès aux fichiers téléchargés. En déclarant le chemin + node_modules +, vous vous assurez que l’étape suivante aura accès aux fichiers. Celles-ci pourront également être visualisées ou téléchargées dans l’interface utilisateur de GitLab après le test. Cela est donc utile pour les artefacts de construction tels que les fichiers binaires. Si vous voulez sauvegarder tout ce qui a été produit pendant l’étape, remplacez toute la section + path + 'par + untracked: true + `.

Enfin, le deuxième travail appelé + test_with_lab + déclare la commande qui exécutera réellement la suite de tests:

test_with_lab:
 stage: test
 script: npm test

Nous plaçons ceci dans l’étape + test +. Comme il s’agit d’une étape ultérieure, il a accès aux artefacts produits par l’étape + build +, qui sont les dépendances du projet dans notre cas. Ici, la section + script + montre la syntaxe YAML sur une seule ligne qui peut être utilisée quand il n’ya qu’un seul élément. Nous aurions pu utiliser cette même syntaxe dans le travail précédent car une seule commande était spécifiée.

Maintenant que vous avez une idée de base de la définition des tâches CI / CD dans le fichier + .gitlab-ci.yml +, nous pouvons définir un ou plusieurs exécutants capables d’exécuter le plan de test.

Déclenchement d’un cycle d’intégration continue

Comme notre référentiel comprend un fichier + .gitlab-ci.yml +, toute nouvelle validation déclenchera une nouvelle exécution de CI. Si aucun participant n’est disponible, l’exécution du CI sera définie sur «en attente». Avant de définir un coureur, déclenchons une exécution de CI pour voir à quoi ressemble un travail dans l’état en attente. Une fois qu’un coureur est disponible, il reprend immédiatement la course en attente.

De retour dans la vue du référentiel de projet + hello_hapi + GitLab, cliquez sur le signe * plus * à côté du nom de la branche et du projet et sélectionnez * Nouveau fichier * dans le menu:

image: https: //assets.digitalocean.com/articles/gitlab_ci_usage/new_file_button2.png [Bouton du nouveau fichier GitLab]

Sur la page suivante, entrez + dummy_file + dans le champ * Nom du fichier * et entrez du texte dans la fenêtre d’édition principale:

image: https: //assets.digitalocean.com/articles/gitlab_ci_usage/dummy_file2.png [fichier factice GitLab]

Cliquez sur * Valider les modifications * en bas lorsque vous avez terminé.

Revenons maintenant à la page principale du projet. Une petite icône * en pause * sera attachée au dernier commit. Si vous passez la souris sur l’icône, le message «Commit: pending» (Commit: en attente) apparaît:

image: https: //assets.digitalocean.com/articles/gitlab_ci_usage/pending_marker_2.png [marqueur en attente de GitLab]

Cela signifie que les tests qui valident les modifications de code n’ont pas encore été exécutés.

Pour obtenir plus d’informations, allez en haut de la page et cliquez sur * Pipelines *. Vous serez dirigé vers la page de synthèse du pipeline, où vous pouvez voir que l’exécution du CI est marquée comme en attente et étiquetée comme «bloquée»:

image: https: //assets.digitalocean.com/articles/gitlab_ci_usage/pipeline_index_stuck.png [Index du pipeline GitLab bloqué]

À partir de là, vous pouvez cliquer sur le statut * en attente * pour obtenir plus de détails sur l’exécution. Cette vue affiche les différentes étapes de notre exécution, ainsi que les travaux individuels associés à chaque étape:

image: https: //assets.digitalocean.com/articles/gitlab_ci_usage/pipeline_detail_view.png [Vue détaillée du pipeline GitLab]

Enfin, cliquez sur le travail * install_dependencies *. Cela vous donnera les détails spécifiques sur ce qui retarde la course:

image: https: //assets.digitalocean.com/articles/gitlab_ci_usage/job_detail_view.png [Vue détaillée du travail GitLab]

Ici, le message indique que le travail est bloqué à cause du manque de coureurs. Ceci est attendu puisque nous n’en avons pas encore configuré. Une fois qu’un coureur est disponible, cette même interface peut être utilisée pour voir la sortie. C’est également à cet endroit que vous pouvez télécharger des artefacts produits lors de la construction.

Maintenant que nous savons à quoi ressemble un travail en attente, nous pouvons affecter un coureur de CI à notre projet pour récupérer le travail en attente.

Installation du service GitLab CI Runner

Nous sommes maintenant prêts à configurer un coureur GitLab CI. Pour ce faire, nous devons installer le package GitLab CI Runner sur le système et démarrer le service GitLab Runner. Le service peut exécuter plusieurs instances de coureur pour différents projets.

Comme indiqué dans les conditions préalables, vous pouvez exécuter ces étapes sur le même serveur que celui qui héberge votre instance GitLab ou sur un autre serveur si vous souhaitez être sûr d’éviter le conflit de ressources. N’oubliez pas que, quel que soit l’hôte que vous choisissez, vous devez installer Docker pour la configuration que nous allons utiliser.

Le processus d’installation du service GitLab CI Runner est similaire à celui utilisé pour installer GitLab lui-même. Nous allons télécharger un script pour ajouter un référentiel GitLab à notre liste de sources + apt +. Après avoir exécuté le script, nous téléchargerons le package du coureur. Nous pouvons ensuite le configurer pour servir notre instance GitLab.

Commencez par télécharger la dernière version du script de configuration du référentiel GitLab CI Runner dans le répertoire + / tmp + (il s’agit d’un référentiel différent de celui utilisé par le serveur GitLab):

curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh -o /tmp/gl-runner.deb.sh

N’hésitez pas à examiner le script téléchargé pour vous assurer que vous êtes à l’aise avec les actions qu’il va entreprendre. Vous pouvez également trouver une version hébergée du script here:

less /tmp/gl-runner.deb.sh

Une fois que vous êtes satisfait de la sécurité du script, exécutez le programme d’installation:

sudo bash /tmp/gl-runner.deb.sh

Le script configurera votre serveur pour utiliser les référentiels maintenus par GitLab. Cela vous permet de gérer les packages de coureur GitLab avec les mêmes outils de gestion que ceux que vous utilisez pour vos autres packages système. Une fois cette opération terminée, vous pouvez poursuivre l’installation à l’aide de + apt-get:

sudo apt-get install gitlab-runner

Cela installera le package GitLab CI Runner sur le système et lancera le service GitLab Runner.

Configurer un coureur GitLab

Ensuite, nous devons configurer un coureur GitLab CI afin qu’il puisse commencer à accepter du travail.

Pour ce faire, nous avons besoin d’un jeton de coureur GitLab afin que celui-ci puisse s’authentifier auprès du serveur GitLab. Le type de jeton dont nous avons besoin dépend de la manière dont nous voulons utiliser ce coureur.

Un * coureur spécifique au projet * est utile si vous avez des exigences spécifiques pour le coureur. Par exemple, si votre fichier + gitlab-ci.yml + définit des tâches de déploiement nécessitant des informations d’identification, un exécutant spécifique peut être requis pour s’authentifier correctement dans l’environnement de déploiement. Si votre projet comporte des étapes gourmandes en ressources dans le processus de CI, cela peut également être une bonne idée. Un coureur spécifique au projet n’acceptera pas les travaux d’autres projets.

D’autre part, un * coureur partagé * est un coureur à usage général pouvant être utilisé par plusieurs projets. Les coureurs prendront les tâches des projets selon un algorithme qui tient compte du nombre de tâches en cours d’exécution pour chaque projet. Ce type de coureur est plus flexible. Vous devrez vous connecter à GitLab avec un compte administrateur pour configurer des coureurs partagés.

Nous montrerons comment obtenir les jetons Coureur pour ces deux types de coureurs ci-dessous. Choisissez la méthode qui vous convient le mieux.

Collecte d’informations pour enregistrer un coureur spécifique à un projet

Si vous souhaitez que le coureur soit lié à un projet spécifique, commencez par accéder à la page du projet dans l’interface GitLab.

À partir de là, cliquez sur l’option * Paramètres * dans le menu de gauche. Ensuite, cliquez sur l’élément * CI / CD * dans le sous-menu:

image: https: //assets.digitalocean.com/articles/gitlab_ci_usage/project_settings_item2.png [Elément de paramétrage du projet GitLab]

Sur cette page, vous verrez une section * Paramètres des coureurs *. Cliquez sur le bouton * Développer * pour voir plus de détails. Dans la vue détaillée, le côté gauche explique comment enregistrer un coureur spécifique au projet. Copiez le jeton d’enregistrement affiché à l’étape 4 des instructions:

image: https: //assets.digitalocean.com/articles/gitlab_ci_usage/specific_runner_config_settings2.png [Paramètres de configuration de runner spécifiques à GitLab]

Si vous souhaitez désactiver des coureurs partagés actifs pour ce projet, vous pouvez le faire en cliquant sur le bouton * Désactiver les coureurs partagés * situé à droite. C’est facultatif.

Lorsque vous êtes prêt, continuez pour apprendre à inscrire votre coureur en utilisant les informations que vous avez collectées à partir de cette page.

Collecte d’informations pour enregistrer un coureur partagé

Pour trouver les informations nécessaires à l’enregistrement d’un coureur partagé, vous devez être connecté avec un compte administratif.

Commencez par cliquer sur l’icône * clé * dans la barre de navigation supérieure pour accéder à la zone d’administration. Dans la section * Overview * du menu de gauche, cliquez sur * Runners * pour accéder à la page de configuration du coureur partagé:

image: https: //assets.digitalocean.com/articles/gitlab_ci_usage/admin_area_icon2.png [Icône de zone d’administration GitLab]

Copiez le jeton d’enregistrement affiché en haut de la page:

image: https: //assets.digitalocean.com/articles/gitlab_ci_usage/shared_runner_token2.png [Jeton de coureur partagé par GitLab]

Nous utiliserons ce jeton pour enregistrer un coureur GitLab CI pour le projet.

Enregistrement d’un coureur GitLab CI avec le serveur GitLab

Maintenant que vous avez un jeton, retournez sur le serveur sur lequel votre service GitLab CI Runner est installé.

Pour inscrire un nouveau coureur, tapez la commande suivante:

sudo gitlab-runner register

Une série de questions vous sera posée pour configurer le coureur:

Veuillez entrer l’URL du coordinateur gitlab-ci (par exemple, https://gitlab.com/)*

Entrez le nom de domaine de votre serveur GitLab, en utilisant + https: // + pour spécifier SSL. Vous pouvez éventuellement ajouter + / ci + à la fin de votre domaine, mais les versions récentes redirigeront automatiquement.

Veuillez entrer le jeton gitlab-ci pour ce coureur *

Le jeton que vous avez copié dans la dernière section.

Veuillez saisir la description de gitlab-ci pour ce coureur *

Un nom pour ce coureur particulier. Cela apparaîtra dans la liste des coureurs du service des coureurs sur la ligne de commande et dans l’interface GitLab.

Veuillez entrer les tags gitlab-ci pour ce coureur (séparés par une virgule) *

Ce sont des tags que vous pouvez attribuer au coureur. Les jobs GitLab peuvent exprimer des exigences en termes de ces balises pour s’assurer qu’elles sont exécutées sur un hôte avec les dépendances correctes.

Vous pouvez laisser ce champ vide dans ce cas.

S’il faut verrouiller Runner au projet actuel [true / false] *

Assigne le coureur au projet spécifique. Il ne peut pas être utilisé par d’autres projets.

Sélectionnez «faux» ici.

S’il vous plaît entrer l’exécuteur *

La méthode utilisée par le coureur pour terminer les travaux.

Choisissez «docker» ici.

Veuillez entrer l’image par défaut de Docker (par exemple rubis: 2.1) *

L’image par défaut utilisée pour exécuter des travaux lorsque le fichier + .gitlab-ci.yml + n’inclut pas de spécification d’image. Il est préférable de spécifier ici une image générale et de définir des images plus spécifiques dans votre fichier + .gitlab-ci.yml +, comme nous l’avons fait.

Nous allons entrer «alpine: latest» ici comme petit paramètre sécurisé.

Après avoir répondu aux invites, un nouveau coureur sera créé, capable d’exécuter les tâches CI / CD de votre projet.

Vous pouvez voir les coureurs actuellement disponibles dans le service GitLab CI Runner en tapant:

sudo gitlab-runner list

OutputListing configured runners                          ConfigFile=/etc/gitlab-runner/config.toml
example-runner                                      Executor=docker Token=e746250e282d197baa83c67eda2c0b URL=https://example.com

Maintenant que nous avons un coureur disponible, nous pouvons revenir au projet dans GitLab.

Visualiser le CI / CD Run dans GitLab

De retour dans votre navigateur Web, revenez à votre projet dans GitLab. Selon le temps écoulé depuis l’enregistrement de votre coureur, le coureur peut être en cours d’exécution:

image: https: //assets.digitalocean.com/articles/gitlab_ci_usage/ci_running_icon_2.png [Icône en cours d’exécution de GitLab CI]

Ou cela aurait déjà été fait:

image: https: //assets.digitalocean.com/articles/gitlab_ci_usage/ci_run_passed_icon_2.png [Icône GitLab exécutée avec succès]

Indépendamment de l’état, cliquez sur l’icône * en cours * ou * passé * (ou * en cas d’échec * si vous rencontrez un problème) pour afficher l’état actuel de l’exécution du CI. Vous pouvez obtenir une vue similaire en cliquant sur le menu supérieur * Pipelines *.

Vous serez dirigé vers la page de présentation du pipeline où vous pouvez voir le statut de l’exécution de GitLab CI:

image: https: //assets.digitalocean.com/articles/gitlab_ci_usage/pipeline_run_overview.png [Présentation générale de l’exécution du pipeline GitLab CI]

Sous l’entête * Stages *, il y aura un cercle indiquant le statut de chacune des étapes de la course. Si vous cliquez sur la scène, vous pouvez voir les travaux individuels associés à la scène:

image: https: //assets.digitalocean.com/articles/gitlab_ci_usage/pipeline_run_stage_view.png [Exécution du pipeline GitLab CI: stage_view]

Cliquez sur le travail * install_dependencies * dans l’étape * build *. Cela vous mènera à la page d’aperçu du travail:

image: https: //assets.digitalocean.com/articles/gitlab_ci_usage/pipeline_job_overview.png [Présentation du travail de pipeline GitLab CI]

Désormais, au lieu d’afficher un message indiquant qu’aucun coureur n’est disponible, la sortie du travail est affichée. Dans notre cas, cela signifie que vous pouvez voir les résultats de l’installation de chacun des paquetages + npm +.

Sur le côté droit, vous pouvez également voir d’autres éléments. Vous pouvez afficher d’autres tâches en modifiant * Stage * et en cliquant sur les exécutions ci-dessous. Vous pouvez également afficher ou télécharger tous les artefacts produits lors de la course.

Conclusion

Dans ce guide, nous avons ajouté un projet de démonstration à une instance de GitLab afin de mettre en évidence les capacités d’intégration et de déploiement continus de GitLab CI. Nous avons expliqué comment définir un pipeline dans les fichiers + gitlab-ci.yml + pour construire et tester vos applications et comment affecter des travaux à des étapes afin de définir leurs relations mutuelles. Nous avons ensuite configuré un coureur GitLab CI pour récupérer les travaux CI pour notre projet et avons montré comment trouver des informations sur les exécutions individuelles de GitLab CI.

TOC