URL: https://linuxfr.org/news/boite-a-outils-pour-gitlab-ci Title: Boîte à outils pour GitLab CI Authors: Emeric Davy Defaud, palm123, ZeroHeure, Xavier Teyssier, Benoît Sibaud et elionne Date: 2018年01月07日T20:32:39+01:00 License: CC By-SA Tags: gitlab, gitlab-ci et postgresql Score: 38 Le projet que je vais développer ici est une boîte à outils pour Gitlab CI publié sous licence GNU GPL v3, dont la fonction principale est d’exécuter les tâches GitLab manuellement, individuellement et simplement sur votre station de développement. J’ai commencé son développement début 2017 dans le cadre de ma mission chez ERCOM et, à ce jour, il a atteint un bon stade de maturité. Il est désormais utilisé par deux équipes sur au moins une dizaine de projets. [GitLab](https://fr.wikipedia.org/wiki/GitLab_CE) (_Community Edition_) est un logiciel libre, sous licence MIT. Il s’agit d’une forge logicielle équivalente à [GitHub](https://fr.wikipedia.org/wiki/GitHub) et la partie mentionnée, [GitLab CI](https://about.gitlab.com/features/gitlab-ci-cd/), est une fonctionnalité d’intégration continue équivalente au service [Travis CI](https://fr.wikipedia.org/wiki/Travis_CI) ![logo GitLab](https://upload.wikimedia.org/wikipedia/commons/thumb/1/18/GitLab_Logo.svg/170px-GitLab_Logo.svg.png) ---- [Page du projet](https://gitlab.com/ercom/citbx4gitlab) [GitLab CI](https://about.gitlab.com/features/gitlab-ci-cd/) [Page Wikipedia de GitLab CE](https://fr.wikipedia.org/wiki/GitLab_CE) [GitLab](https://gitlab.com/) ---- # citbx4gitlab : boîte à outils pour GitLab CI Cette boîte à outils apporte principalement : * fonction de base : exécuter les tâches GitLab manuellement et individuellement sur votre station de développement en dehors d’un exécuteur de tâches GitLab (outil `gitlab-runner`) sans avoir à valider un enregistrement et pousser une branche sur le serveur GitLab ce qui lancera un _pipeline_ complet ; * fonction avancée : définir des scripts avancés qui peuvent être exécutés de la même manière sur l’exécuteur GitLab et la station de travail standard. ## Le projet Exemple d’intégration de la boîte à outils dans une arborescence de projet : ``` ├── .gitlab-ci.yml ├── tools │ └── gitlab-ci │ ├── 3rdparty │ │ └── bashopts.sh │ ├── citbx.properties │ ├── env-setup │ │ ├── common.sh │ │ ├── gentoo.sh │ │ └── ubuntu.sh │ ├── modules │ │ ├── ccache.sh │ │ ├── dockerimg.sh │ │ └── example.sh │ ├── run -> run.sh │ ├── run.d │ │ └── job-advanced.sh │ └── run.sh ``` Liste des éléments essentiels : * `.gitlab-ci.yml` : définition du _pipeline_ de tâches GitLab ; * `run.sh`: script de lancement de tâche GitLab CI exécuté indirectement via la commande `ci-toolbox` ; * `bashopts.sh` : dépendance externe nécessaire pour la boîte à outils. Liste des éléments recommandés : * `env-setup` : dossier contenant les routines d’installation de l’environnement pour faire tourner la boîte à outils ; * `citbx.properties` : propriétés de la boîte à outils propre au projet cible. Liste des éléments pour une utilisation avancée : * `run.d` : dossier contenant les fonctions spécifiques à certaines tâches ; * `modules` : dossier contenant les modules. ## Cas d’utilisation : tâche de pipeline GitLab standard Le schéma suivant décrit l’exécution d’une tâche standard appelée « J » dans un _pipeline_ Gitlab CI : ![Cas d’utilisation global](https://gitlab.com/ercom/citbx4gitlab/raw/3.3.1/doc/GitlabCIPipelineJob.png) Dans ce cas, il serait intéressant d’exécuter une tâche spécifique comme _J_ dans son environnement approprié sur votre poste de travail local, sans avoir à valider un enregistrement (`git commit`) ni avoir à pousser votre dépôt (`git push`). Le but est d’avoir exactement le même environnement de construction sur l’exécuteur de tâche GitLab et votre poste de travail local. ![Cas d’utilisation d’une tâche unique](https://gitlab.com/ercom/citbx4gitlab/raw/3.3.1/doc/GitlabCISingleJob.png) ## Exécuter une tâche spécifique localement ### Première solution : utiliser l’outil gitlab-runner Pour utiliser cette solution, vous devrez : * installer l’outil `gitlab-runner` sur le poste de travail ; * et le lancer de la manière suivante : `gitlab-runner exec `. Vous devrez : * valider tous les changements locaux dans des enregistrements Git ; * ajouter des options supplémentaires à `gitlab-runner` du type `--docker-image` avec le nom de l’image appropriée. ### L'autre solution : la commande ci-toolbox Cette boîte à outils est capable de le faire : * démarrer une tâche de type script ou `docker` avec les paramètres appropriés (image, etc.) ; * lancer une tâche du _pipeline_ localement sans avoir à valider un enregistrement (`git commit`). Fonctions additionnelles pour une utilisation avancée : * ajouter des paramètres et des actions spécifiques au poste de travail ; * ajouter la possibilité d’exécuter une invite de commande dans l’environnement Docker approprié ; * diviser les différentes tâches du _pipeline_ de façon modulaire. Utilisation : * `ci-toolbox [arguments...]`, depuis n’importe quel endroit dans l’arborescence du projet ; * ou bien : `chemin/du/run.sh [arguments...]`. L’outil `ci-toolbox` est installé dans le système durant la phase de paramétrage `path/to/run.sh setup` et ajoute les fonctionnalités suivantes : * cet outil peut être exécuté n’importe où dans l’arborescence du projet contenant le script `run.sh` ; * cet outil est comme un raccourci pour trouver et exécuter le script `run.sh` sans avoir à spécifier le chemin absolu ou relatif ; * cet outil permet d’ajouter la prise en charge de l’auto‐complétion Bash sur le nom des tâches du _pipeline_ GitLab et des options associées. Les limites connues de la boîte à outils : elle n’est applicable uniquement que pour les types d’exécuteur de tâche GitLab `docker` et `shell`. ## Écrire une tâche ou un module en utilisant la boîte à outils En plus de pouvoir lancer une tâche du _pipeline_ (comme la tâche [job-minimal](#job-minimal)), vous pouvez utiliser la boîte à outils pour écrire les scripts de celle‐ci avec une structure modulaire, comme c’est le cas pour la tâche d’exemple [_job-advanced_](#job-advanced). ![Ordre d’exécution des types de routines](https://gitlab.com/ercom/citbx4gitlab/raw/3.3.1/doc/HookExecutionOrder.png) ### Écrire une tâche Les routines spécifiques à la tâche en question doivent être écrites dans un script qui porte le nom de cette dernière dans le dossier : `run.d/.sh`. Ce job peut faire appel à différents modules utilisant : `citbx_use ""`. Le job peut définir les routines suivantes — uniquement applicables à un poste de travail local : * `job_define()` : cette fonction peut être utilisée pour définir des options pour le cas d’utilisation sur un poste de travail ; * `job_setup()` : cette fonction peut être utilisée pour effectuer une action avant de configurer et démarrer l’environnement de la tâche (`docker run`). La tâche peut définir les routines suivantes - applicables à tous les environnements : * `job_main()` : la fonction principale de la tâche qui contient la charge utile ; * `job_after()` : cette fonction peut être utilisée pour effectuer une action après l’exécution de la fonction `job_main` et est appelée dans **tous** les cas (succès ou erreur) ; elle est appelée avec le code de retour du processus comme premier argument (0 en cas de succès). Exemple de script de tâche : [`tools/gitlab-ci/run.d/job-advanced.sh`](https://gitlab.com/ercom/citbx4gitlab/raw/3.3.1/tools/gitlab-ci/run.d/job-advanced.sh). ### Écriture d’un module Le module doit être défini dans `modules/.sh`. Ce module peut utiliser d’autres modules à l’aide de `citbx_use ""`. Le module peut définir les routines suivantes — uniquement applicables à un poste de travail local : * `citbx_module__define()` : cette fonction peut être utilisée pour définir des options pour le cas d’utilisation sur un poste de travail ; * `citbx_module__setup()` : cette fonction peut être utilisée pour effectuer une action avant de configurer et démarrer l’environnement de la tâche (`docker run`). Le job peut définir les routines suivantes — applicables à tous les environnements : * `citbx_module__before()` : cette fonction peut être utilisée pour effectuer une action avant l’exécution du job principal ; * `citbx_module__after()` : cette fonction peut être utilisée pour effectuer une action après l’exécution du job principal et est appelée dans **tous** les cas (succès ou erreur) ; elle est appelée avec le code de retour du processus comme premier argument (0 en cas de succès). Exemple de script de module : [`tools/gitlab-ci/modules/example.sh`](https://gitlab.com/ercom/citbx4gitlab/raw/3.3.1/tools/gitlab-ci/modules/example.sh). ### Liste des fonctions utiles * `citbx_run_ext_job ` : exécuter une autre tâche ; * `citbx_job_list [prefix]` : obtenir la liste des tâches (en option : avec le préfixe spécifié) ; * `citbx_use ` : charger un module ; * `print_critical ` : affichage d’un message d’erreur et sortie (code de sortie : 1) ; * `print_error ` : affichage un message d’erreur ; * `print_warning ` : affichage un message d’avertissement . * `print_note ` : affichage un message de note ; * `print_info ` : affichage un message d’information. ## Exemples de tâches ### job-minimal Exemple de tâche minimaliste. Définition de la tâche : ```yaml image: ubuntu:16.04 job-minimal: stage: all-in-one script: - echo "Bonjour monde !" after_script: - echo "job ${CI_JOB_NAME} end" ``` Exécution de la tâche : ![Tâche minimaliste](https://gitlab.com/ercom/citbx4gitlab/raw/3.3.1/doc/TestCaseJobMinimal.png) ### job-with-before-after-script Exemple de définition de tâche avec les propriétés `before_script` et `after_script` : Définition de la tâche : ```yaml after_script: - echo "job ${CI_JOB_NAME} end" job-with-before-after-script: stage: all-in-one before_script: - echo "exécuté avant" script: - echo "script" "sur plusieurs" - echo "lignes" - cat <<< $(echo 'salut !') after_script: - echo "exécuté après" ``` ### job-advanced Exemple de définition d’un job (fichier [`tools/gitlab-ci/run.d/job-advanced.sh`](https://gitlab.com/ercom/citbx4gitlab/raw/3.3.1/tools/gitlab-ci/run.d/job-advanced.sh)) avec options, arguments, traitements supplémentaires et utilisation de modules externes (fichier [`tools/gitlab-ci/modules/example.sh`](https://gitlab.com/ercom/citbx4gitlab/raw/3.3.1/tools/gitlab-ci/modules/example.sh)). Définition de la tâche : ```yaml job-advanced: image: ubuntu:16.04 stage: all-in-one variables: JOBADVAR: "${CI_JOB_NAME} JOBADVAR value" script: - echo ${GLOBALJOBVAR} - echo ${JOBADVAR} - tools/gitlab-ci/run.sh after_script: - echo "job ${CI_JOB_NAME} end" ``` Exécution de la tâche : ![Tâche avancée](https://gitlab.com/ercom/citbx4gitlab/raw/3.3.1/doc/TestCaseJobAvanced.png) ### job-test-services-mysql Exemple de définition de tâche avec un service MySQL. Définition de la tâche : ```yaml job-test-services-mysql: stage: build variables: MYSQL_DATABASE: test MYSQL_ROOT_PASSWORD: password CITBX_WAIT_FOR_SERVICE_START: 10 image: mysql services: - mysql tags: - test script: - mysql -h mysql -u root -ppassword test -e 'SHOW VARIABLES LIKE "%version%";' ``` ### job-test-services-postgres Exemple de définition de tâche avec un service PostgreSQL. Définition de la tâche : ```yaml job-test-services-postgres: stage: build variables: CITBX_WAIT_FOR_SERVICE_START: 10 image: postgres:9.4 services: - name: postgres:9.4 alias: db-postgres entrypoint: ["docker-entrypoint.sh"] command: ["postgres"] tags: - test script: - psql -h db-postgres -U postgres -c 'select version();' ```

AltStyle によって変換されたページ (->オリジナル) /