Conseils pour créer des workflows personnalisés dans GitLab CI

Remarque perev. : L'article original a été écrit par Miłosz Smółka, l'un des fondateurs de la petite entreprise polonaise Three Dots Labs , spécialisée dans les «solutions avancées de backend». L'auteur s'appuie sur son expérience dans l'utilisation active de GitLab CI et partage les conseils accumulés pour les autres utilisateurs de ce produit Open Source. Après les avoir lus, nous avons réalisé à quel point les problèmes décrits par lui étaient proches de nous, nous avons donc décidé de partager les solutions proposées avec un public plus large.



Cette fois, je couvrirai des sujets plus avancés dans GitLab CI. Une tâche courante consiste à implémenter des fonctionnalités non standard dans le pipeline. La plupart des conseils sont spécifiques à GitLab, bien que certains d'entre eux puissent être appliqués à d'autres systèmes CI.

Exécutez des tests d'intégration

En règle générale, la vérification du code à l'aide de tests unitaires est facile à connecter à n'importe quel système CI. Habituellement, cela n'est pas plus compliqué que d'exécuter l'une des commandes intégrées à l'ensemble standard d'utilitaires dans un langage de programmation. Dans de tels tests, vous êtes susceptible d'utiliser divers moki et stubs pour masquer les détails d'implémentation et vous concentrer sur le test d'une logique spécifique. Par exemple, vous pouvez utiliser la base de données en mémoire comme stockage ou écrire des talons pour les clients HTTP qui renverront toujours des réponses déjà préparées.

Cependant, tôt ou tard, vous aurez besoin de tests d'intégration pour couvrir des situations plus inhabituelles avec des tests. Je n'entrerai pas dans la discussion sur tous les types de tests possibles et je dirai simplement que par intégration, je veux dire les tests qui utilisent une sorte de ressources externes. Il peut s'agir d'un véritable serveur de base de données, d'un service HTTP, d'un stockage connecté, etc.

Dans GitLab, il est facile d'exécuter des ressources enfichables en tant que conteneurs Docker associés au conteneur dans lequel les scripts s'exécutent. Ces dépendances peuvent être définies à l'aide de services . Ils sont disponibles par le nom de l'image ou par le nom de votre choix, si vous le spécifiez dans le champ alias .

Voici un exemple simple d'utilisation d'un conteneur enfichable avec MySQL:

 integration_tests: stage: tests services: - name: mysql:8 alias: db script: - ./run_tests.sh db:3306 

Dans ce cas, dans les scripts de test, vous devrez vous connecter à l'hôte db . L'utilisation d'un alias est généralement une bonne idée, car elle vous permet de remplacer des images sans avoir à modifier le code de test. Par exemple, vous pouvez remplacer l'image mysql par mariadb , et le script fonctionnera toujours correctement.

En attente de conteneurs

Étant donné que les conteneurs de plug-ins prennent du temps à charger, vous devrez peut-être attendre avant d'envoyer des demandes. Un moyen simple est d' attendre le script wait-for-it.sh avec un timeout défini.

Utilisation de Docker Compose

Dans la plupart des cas, les services devraient être suffisants. Cependant, une interaction avec des services externes peut parfois être nécessaire. Par exemple, dans le cas du lancement de Kafka et ZooKeeper dans deux conteneurs distincts (c'est ainsi que les images officielles sont collectées). Un autre exemple est l'exécution de tests avec un nombre dynamique de nœuds, tels que Selenium. La meilleure solution pour exécuter ces services serait Docker Compose :

 version: '3' services: zookeeper: image: confluentinc/cp-zookeeper environment: ZOOKEEPER_CLIENT_PORT: 2181 kafka: image: confluentinc/cp-kafka environment: KAFKA_ZOOKEEPER_CONNECT: zookeeper:2181 KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://kafka:9092 ports: - 9092:9092 

Si vous utilisez votre installation avec des exécuteurs GitLab sur des serveurs fiables, vous pouvez exécuter Docker Composer via l' exécuteur Shell . Une autre option possible est le dind Docker in Docker ( dind ). Mais dans ce cas, lisez d'abord cet article .

Une façon d'utiliser Compose est de configurer votre environnement, d'exécuter des tests, puis de tout détruire. Un simple script bash ressemblerait à ceci:

 docker-compose up -d ./run_tests.sh localhost:9092 docker-compose down 

Tant que vous exécutez des tests dans un environnement minimal, tout ira bien. Bien qu'une situation puisse survenir dans laquelle vous devez installer certaines dépendances ... Il existe une autre façon d'exécuter des tests dans Docker Compose - elle vous permet de créer votre propre image Docker avec un environnement de test. Dans l'un des conteneurs, vous exécutez des tests et quittez avec le code retour correspondant:

 version: '3' services: zookeeper: image: confluentinc/cp-zookeeper environment: ZOOKEEPER_CLIENT_PORT: 2181 kafka: image: confluentinc/cp-kafka environment: KAFKA_ZOOKEEPER_CONNECT: zookeeper:2181 KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://kafka:9092 tests: image: registry.example.com/some-image command: ./run_tests.sh kafka:9092 

Notez que nous avons éliminé la nécessité de mapper les ports. Dans cet exemple, les tests peuvent interagir directement avec tous les services.

Et leur lancement s'effectue par une seule commande:

 docker-compose up --exit-code-from tests 

L' --abort-on-container-exit --exit-code-from implique --abort-on-container-exit , ce qui signifie: tout l'environnement initié par docker-compose up sera arrêté après la fin de l'un des conteneurs. Le code d'achèvement de cette commande sera équivalent au code de sortie du service sélectionné (c'est-à-dire qu'il s'agit de tests dans l'exemple ci-dessus). Si la commande qui démarre les tests se termine avec un code différent de zéro, la commande docker-compose up entière se termine avec elle.

Utilisation d'étiquettes comme balises CI

Attention : c'est une idée plutôt inhabituelle, mais elle m'a paru très utile et flexible.

Comme vous le savez peut-être, GitLab dispose d'une fonctionnalité d'étiquettes disponible au niveau du projet et du groupe. Des étiquettes peuvent être définies sur les tickets et les demandes de fusion. Cependant, ils n'ont aucun lien avec les pipelines.



Un petit raffinement vous permettra d'accéder aux libellés de la demande de fusion dans les scripts de jobs. Dans GitLab 11.6, tout est devenu encore plus facile, car la variable d'environnement CI_MERGE_REQUEST_IID est apparue (oui, c'est avec l' IID , pas l' ID ) si le pipeline utilise only: merge_requests .

Si only: merge_requests pas utilisé ou si vous travaillez avec une ancienne version de GitLab, MR peut toujours être obtenu - en utilisant l'appel API:

 curl "$CI_API_V4_URL/projects/$CI_PROJECT_ID/repository/commits/$CI_COMMIT_SHA/merge_requests?private_token=$GITLAB_TOKEN" 

Le domaine dont nous avons besoin est iid . Cependant, n'oubliez pas que de nombreux MR peuvent revenir pour un commit donné.

Lorsque le MR IID est reçu, il ne reste plus qu'à se tourner vers l' API Merge Requests et à utiliser le champ des labels de la réponse:

 curl "$CI_API_V4_URL/projects/$CI_PROJECT_ID/merge_requests/$CI_MERGE_REQUEST_IID?private_token=$GITLAB_TOKEN" 

Se connecter

Malheureusement, pour le moment, il n'est pas possible d'utiliser $CI_JOB_TOKEN pour accéder à l'API du projet (au moins si le projet n'est pas public). Si le projet a un accès limité (interne ou privé), pour l'autorisation dans l'API GitLab, vous devrez générer un jeton d'API personnel.



Cependant, ce n'est pas la solution la plus sûre, alors soyez prudent. Si le jeton tombe entre de mauvaises mains, l'accès en écriture à tous vos projets peut apparaître avec lui. Une façon de réduire les risques consiste à créer un compte distinct avec le droit de lire le référentiel et de générer un jeton personnel pour ce compte.

Vos variables sont-elles sûres?

Il y a quelques versions, la section Variables s'appelait Variables secrètes , ce qui semble avoir été créé pour stocker de manière fiable les informations d'identification et autres informations critiques. En fait, les variables sont simplement cachées aux utilisateurs qui ne disposent pas des privilèges du responsable. Ils ne sont pas chiffrés sur le disque et leur fuite peut facilement se produire via des variables d'environnement dans les scripts.

Gardez cela à l'esprit lorsque vous ajoutez des variables et envisagez de garder des secrets dans des solutions plus sécurisées (par exemple, Vault de HashiCorp ).

Cas d'utilisation

Que faire des listes d'étiquettes dépend de vous. Voici quelques idées:

• Utilisez-les pour segmenter les tests.
• Utilisez la sémantique des valeurs-clés avec deux points comme séparateur (par exemple, des étiquettes comme tests:auth , tests:user )
• Inclure certaines fonctionnalités pour les travaux.
• Autorisez le débogage de travaux spécifiques si l'étiquette existe.

Appel d'API externes

Bien que GitLab soit livré avec une gamme de fonctionnalités déjà disponibles, il est très probable que vous souhaitiez utiliser d'autres utilitaires pouvant être intégrés aux pipelines. La façon la plus simple de l'implémenter est, bien sûr, d'appeler la bonne vieille curl .

Si vous créez vos propres outils, vous pouvez leur apprendre à écouter les Webhooks GitLab (voir l'onglet Intégrations dans les paramètres du projet). Cependant, si vous avez l'intention de les utiliser avec des systèmes critiques, assurez-vous qu'ils répondent aux exigences de haute disponibilité.

Exemple: annotations Grafana

Si vous travaillez avec Grafana , les annotations sont un excellent moyen de marquer des événements qui se sont produits au fil du temps sur des graphiques. Ils peuvent être ajoutés non seulement manuellement en cliquant dans l'interface graphique, mais également en appelant l' API REST Grafana :



Pour accéder à l'API, vous devrez générer une clé API. Envisagez de créer un utilisateur distinct avec un accès limité:



Définissez deux variables dans les paramètres du projet:

• GRAFANA_URL - URL de l'installation de Grafana (par exemple, https://grafana.example.com );
• GRAFANA_APIKEY - clé générée pour l'API.

Pour pouvoir le réutiliser, placez le script dans le référentiel avec des scripts communs :

 #!/bin/bash set -e if [ $# -lt 2 ]; then echo "Usage: $0 <text> <tag>" exit 1 fi readonly text="$1" readonly tag="$2" readonly time="$(date +%s)000" cat >./payload.json <<EOF { "text": "$text", "tags": ["$tag"], "time": $time, "timeEnd": $time } EOF curl -X POST "$GRAFANA_URL/api/annotations" \ -H "Authorization: Bearer $GRAFANA_APIKEY" \ -H "content-type: application/json" \ -d @./payload.json 

Vous pouvez maintenant ajouter son appel à la configuration CI avec les paramètres nécessaires:

 deploy: stage: deploy script: - $SCRIPTS_DIR/deploy.sh production - $SCRIPTS_DIR/grafana-annotation.sh "$VERSION deployed to production" deploy-production 

Ces appels peuvent être placés dans le script deploy.sh pour simplifier la configuration CI.

Bonus: conseils rapides

GitLab a une excellente documentation sur tous les mots clés possibles qui peuvent être utilisés pour configurer CI. Je ne veux pas dupliquer son contenu ici, mais je soulignerai quelques cas utiles. Cliquez sur les titres pour voir la documentation associée.

Utilisation avancée de seulement / sauf

En définissant des modèles pour les variables CI, vous pouvez définir des assemblages personnalisés pour certaines branches. Cela peut aider, par exemple, à identifier les correctifs push pour les correctifs urgents, mais n'en abusez pas:

 only: refs: - branches variables: - $CI_COMMIT_REF_NAME =~ /^hotfix/ 

GitLab a de nombreuses variables prédéfinies dans chaque travail CI - utilisez-les.

Ancres Yaml

Utilisez-les pour éviter les doublons.

À partir de la version 11.3, vous pouvez également utiliser le mot clé extend :

 .common_before_script: &common_before_script before_script: - ... - ... deploy: <<: *common_before_script 

Exclusion d'artefacts

Par défaut, tous les artefacts collectés dans le pipeline seront transférés vers tous les travaux suivants. Si vous répertoriez explicitement les artefacts dont dépendent les travaux, vous pouvez économiser du temps et de l'espace disque:

 dependencies: - build 

Ou - au contraire - sautez complètement tout si aucun n'est requis:

 dependencies: [] 

Stratégie Git

Ignorer le clonage du référentiel si le travail n'utilise pas ces fichiers:

 variables: GIT_STRATEGY: none 

C’est tout!

Merci d'avoir lu! Pour des commentaires et des questions, contactez-moi sur Twitter ou Reddit .

Plus de conseils GitLab peuvent être trouvés dans les articles précédents:

• Conserver les scripts communs dans GitLab CI ;
• Versioning sémantique automatique dans GitLab CI .

PS du traducteur

Lisez aussi dans notre blog:

• « GitLab CI pour une intégration et une livraison continues en production. Partie 1: notre pipeline »;
• « GitLab CI pour une intégration et une livraison continues en production. Partie 2: surmonter les difficultés »;
• « Créez des projets avec GitLab CI: un .gitlab-ci.yml pour des centaines d'applications »;
• « Créer et installer des applications dans Kubernetes à l'aide de dapp et GitLab CI »;
• " Meilleures pratiques pour CI / CD avec Kubernetes et GitLab (revue et rapport vidéo) ."