README.fr.md 13.5 KB
Newer Older
1
# citbx4gitlab : Boîte à outils CI pour Gitlab
2 3 4

Cette boîte à outils peut être utilisée pour

5
* exécuter une tâche Gitlab en dehors d'un exécuteur de tâche Gitlab (outil `gitlab-runner`) sur votre poste de travail (fonction de base)
6
* écrire la partie script en utilisant une structure modulaire (fonction avancée)
7 8 9 10

## Table des matières

* [Le projet](#le-projet)
11 12
    * [Installation de l'outil ci-toolbox](#installation-de-loutil-ci-toolbox)
    * [Mise à jours de l'outil ci-toolbox](#mise-à-jours-de-loutil-ci-toolbox)
13
    * [Intégration dans une arborescence projet](#intégration-dans-une-arborescence-projet)
14
    * [Mise à jour de l'outil ci-toolbox du projet](#mise-à-jour-de-loutil-ci-toolbox-du-projet)
15 16
* [Cas d'utilisation : Tâche de pipeline Gitlab standard](#cas-dutilisation--tâche-de-pipeline-gitlab-standard)
* [Exécuter une tâche spécifique localement](#exécuter-une-tâche-spécifique-localement)
17 18 19 20
    * [Première solution : utiliser l'outil gitlab-runner](#première-solution--utiliser-loutil-gitlab-runner)
    * [La seconde solution : la commande ci-toolbox](#la-seconde-solution--la-commande-ci-toolbox)
* [Écrire une tâche ou un module en utilisant la boîte à outils](#Écrire-une-tâche-ou-un-module-en-utilisant-la-boîte-à-outils)
    * [Écrire une tâche](#Écrire-une-tâche)
21 22
    * [Écriture d'un module](#Écriture-dun-module)
    * [Liste des fonctions utiles](#liste-des-fonctions-utiles)
23
* [Exemples de tâches](#exemples-de-tâches)
24 25 26 27 28
    * [job-minimal](#job-minimal)
    * [job-with-before-after-script](#job-with-before-after-script)
    * [job-advanced](#job-advanced)
    * [job-test-services-mysql](#job-test-services-mysql)
    * [job-test-services-postgres](#job-test-services-postgres)
29 30 31

## Le projet

32
L'outil ci-toolbox peut être installé dans le système et/ou intégré dans l'arborescence de votre projet (ce qui est utile pour forcer l'équipe du projet à utiliser une version spécifique et ainsi maîtriser les mises à jours)
33

34 35
La commande ci-toolbox (`/usr/local/bin/ci-toolbox`) est un outil intermédiaire qui va appeler `tools/ci-toolbox/ci-toolbox.sh` depuis le projet si il est trouvé dedans, autrement, il va exécuter celui installé dans le système (`/usr/local/lib/ci-toolbox/ci-toolbox.sh`)

36
### Installation de l'outil ci-toolbox
37

38
L'installation peut se faire :
39
* Manuellement en clonant le projet et en lançant le script `./tools/ci-toolbox/ci-toolbox.sh setup`
40 41 42 43 44 45 46 47 48 49 50 51
* En copiant ce qui suit dans une invite de commande (en remplaçant si besoin 'master' par le numéro de version choisi dans l'URL) :

```bash
mkdir -p /tmp/ci-toolbox \
    && curl -fSsL https://gitlab.com/ercom/citbx4gitlab/repository/master/archive.tar.bz2 \
    | tar -xj -C /tmp/ci-toolbox \
    && cd /tmp/ci-toolbox/* \
    && ./tools/ci-toolbox/ci-toolbox.sh setup \
    && cd - \
    && rm -rf /tmp/ci-toolbox
```

52
### Mise à jours de l'outil ci-toolbox
53 54 55 56 57

Il suffit de taper la commande `ci-toolbox setup --component ci-tools` ou `ci-toolbox setup --component ci-tools <custom_version>`

### Intégration dans une arborescence projet

58
Cas d'intégration de l'outil ci-toolbox dans une arborescence projet :
59 60 61
```
├── .gitlab-ci.yml
├── tools
62
│   └── ci-toolbox
63 64 65 66 67 68 69 70 71
│       ├── 3rdparty
│       │   └── bashopts.sh
│       ├── env-setup
│       │   ├── common.sh
│       │   ├── gentoo.sh
│       │   └── ubuntu.sh
│       ├── modules
│       │   ├── ccache.sh
│       │   └── example.sh
72
│       ├── jobs
73
│       │   └── job-advanced.sh
74 75
│       ├── ci-toolbox.properties
│       └── ci-toolbox.sh
76 77 78 79
```

Liste des éléments essentiels :

80 81 82
* `.gitlab-ci.yml` : Définition du pipeline de tâches Gitlab
* `ci-toolbox.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
83

84
Liste des éléments recommandés :
85

86 87
* `env-setup` : dossier contenant les routines d'installation de l'environnement pour faire tourner la boîte à outils
* `ci-toolbox.properties` : Propriétés de la boîte à outils propre au projet cible
88 89 90

Liste des éléments pour une utilisation avancée :

91 92
* `jobs` : dossier contenant les fonctions spécifiques aux différentes tâches
* `modules` : dossier contenant les modules
93

94
### Mise à jour de l'outil ci-toolbox du projet
95

96
La commande `ci-toolbox update` ou `ci-toolbox update <custom_version>` permet de mettre à jour de l'outil ci-toolbox de votre projet
97

98 99 100 101 102 103 104 105
## 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](doc/GitlabCIPipelineJob.png)

Dans ce cas, il serait intéressant d'exécuter une tâche spécifique comme J dans leur environnement approprié sur votre poste de travail local sans avoir à valider un enregistrement (`git commit`) ni avoir à pousser votre dépôt (`git push`).

106
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.
107 108 109 110 111

![Cas d'utilisation d'une tâche unique](doc/GitlabCISingleJob.png)

## Exécuter une tâche spécifique localement

112
### Première solution : utiliser l'outil gitlab-runner
113

114
Pour utiliser cette solution, vous devrez :
115 116 117 118

* installer l'outil `gitlab-runner` sur le poste de travail
* et le lancer de la manière suivante : `gitlab-runner exec <type d'exécuteur> <nom de la tâche>`

119
Vous devrez en plus :
120 121 122 123

* valider tous les changements locaux dans des enregistrement GIT
* ajouter des options supplémentaires à `gitlab-runner` du type `--docker-image` avec le nom de l'image appropriée

124 125 126
**NOTE :** La commande `gitlab-runner exe` dépréciée depuis Gitlab 10, et donc susceptible de disparaître

### La seconde solution : la commande ci-toolbox
127

128
Cette boîte à outils est capable de le faire :
129 130 131 132 133 134 135 136 137 138 139 140

* 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âche du pipeline de façon modulaire

Utilisation :

141
* `ci-toolbox <commande> [arguments...]` depuis n'importe quel endroit dans l'arborescence du projet, ... ou bien :
142
* `chemin/du/ci-toolbox.sh <commande> [arguments...]`
143

144
L'outil `ci-toolbox`  est installé dans le système durant la phase de setup `path/to/ci-toolbox.sh setup`, et ajoute les fonctionnalités suivantes :
145

146 147
* Cet outil peut être exécuté n'importe où dans l'arborescence du projet contenant le script `ci-toolbox.sh`
* Cet outil est comme un raccourci pour trouver et exécuter le script `ci-toolbox.sh` sans avoir à spécifier le chemin absolu/relatif
148 149
* 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.

150
Les limites connues de la boîte à outils :
151 152 153

* Applicable uniquement pour les types d'exécuteur de tâche Gitlab `docker` et `shell`

154
## Écrire une tâche ou un module en utilisant la boîte à outils
155

156
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)
157 158 159

![Ordre d'exécution des type de routines](doc/HookExecutionOrder.png)

160
### Écrire une tâche
161

162
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 : `jobs/<nom de la tâche>.sh`
163

164
Cette tâche peut faire appel à différents modules utilisant : `citbx_use "<nom du module>"`
165

166
La tâche peut définir les routines suivantes - Uniquement applicables à un poste de travail local :
167

168 169
* `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)
170 171 172

La tâche peut définir les routines suivantes - applicables à tous les environnements :

173 174
* `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`. Cette fonction est appelée dans TOUS les cas (succès ou erreur). Cette fonction est appelée avec le code de retour du processus comme premier argument (sera égal à 0 sur succès)
175

176
Exemple de script de tâche : [tools/ci-toolbox/jobs/job-advanced.sh](tools/ci-toolbox/jobs/job-advanced.sh)
177 178 179 180 181 182 183

### Écriture d'un module

Le module doit être défini dans `modules/<nom de mon module>.sh`.

Ce module peut utiliser d'autres modules à l'aide de `citbx_use'"<mon autre module>"`.

184
Le module peut définir les routines suivantes - Uniquement applicables à un poste de travail local :
185

186 187
* `citbx_module_<nom de mon 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_<nom de mon 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`)
188

189
La tâche peut définir les routines suivantes - applicables à tous les environnements :
190

191 192
* `citbx_module_<nom de mon module>_before()` : Cette fonction peut être utilisée pour réaliser des actions avant l'exécution de la fonction principale de la tâche `job_main`
* `citbx_module_<nom de mon module>_after()` : Cette fonction peut être utilisée pour réaliser des actions après l'exécution de la fonction principale de la tâche `job_main`. Cette fonction est appelée dans tous les cas (succès ou erreur) avec comme premier argument le code de retour du dernier processus exécuté dans la fonction `job_main` (sera égal à 0 en cas de succès)
193

194
Exemple de script de module : [tools/ci-toolbox/modules/example.sh](tools/ci-toolbox/modules/example.sh)
195 196 197

### Liste des fonctions utiles

198 199 200 201 202 203 204 205
* `citbx_run_ext_job <nom de la tâche>` : 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 <nom du module>` : Charger un module
* `print_critical <message>` : Affichage d'un message d'erreur et sortie (code de retour : 1)
* `print_error <message>` : Affichage un message d'erreur
* `print_warning <message>` : Affichage un message d'avertissement
* `print_note <message>` : Affichage un message de note
* `print_info <message>` : Affichage un message d'information
206 207 208 209 210

## Exemples de tâches

### job-minimal

211
Exemple de de tâche docker minimaliste
212

213
Définition de la tâche :
214 215 216 217 218 219 220 221 222 223 224 225 226

```yaml
image: ubuntu:16.04

job-minimal:
  stage: all-in-one
  script:
    - echo "Bonjour monde !"

after_script:
  - echo "job ${CI_JOB_NAME} end"
```

227
Exécution de la tâche :
228 229 230 231 232

![Tâche minimaliste](doc/TestCaseJobMinimal.png)

### job-with-before-after-script

233
Exemple de définition de tâche docker avec les propriétés `before_script` et `after_script`
234

235
Définition de la tâche :
236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255

```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

256
Exemple de définition d'une tâche docker (fichier [tools/ci-toolbox/jobs/job-advanced.sh](tools/ci-toolbox/jobs/job-advanced.sh)) avec options, arguments, traitements supplémentaires et utilisation de modules externes (fichier [tools/ci-toolbox/modules/example.sh](tools/ci-toolbox/modules/example.sh))
257

258
Définition de la tâche :
259 260 261 262 263 264 265 266 267 268

```yaml
job-advanced:
  image: ubuntu:16.04
  stage: all-in-one
  variables:
    JOBADVAR: "${CI_JOB_NAME} JOBADVAR value"
  script:
    - echo ${GLOBALJOBVAR}
    - echo ${JOBADVAR}
269
    - tools/ci-toolbox/ci-toolbox.sh
270 271 272 273 274

after_script:
  - echo "job ${CI_JOB_NAME} end"
```

275
Exécution de la tâche :
276 277 278 279 280

![Tâche avancée](doc/TestCaseJobAvanced.png)

### job-test-services-mysql

281
Exemple de définition de tâche docker avec un service MySQL
282

283
Définition de la tâche :
284 285 286 287 288 289 290 291 292 293 294

```yaml
job-test-services-mysql:
  stage: build
  variables:
    MYSQL_DATABASE: test
    MYSQL_ROOT_PASSWORD: password
  image: mysql
  services:
    - mysql
  tags:
295
    - docker
296
  script:
297 298 299 300
    - printf "Waiting for mysql";
      while ! mysql -h mysql -u root -ppassword test -e '' > /dev/null 2>&1 ;
      do printf "."; sleep 1; done;
      printf " done!\n"
301 302 303 304 305
    - mysql -h mysql -u root -ppassword test -e 'SHOW VARIABLES LIKE "%version%";'
```

### job-test-services-postgres

306
Exemple de définition de tâche docker avec un service PostgreSQL
307

308
Définition de la tâche :
309 310 311 312 313 314 315 316 317 318 319

```yaml
job-test-services-postgres:
  stage: build
  image: postgres:9.4
  services:
    - name: postgres:9.4
      alias: db-postgres
      entrypoint: ["docker-entrypoint.sh"]
      command: ["postgres"]
  tags:
320
    - docker
321
  script:
322 323 324 325
    - printf "Waiting for postgres";
      while ! psql -h db-postgres -U postgres -c '' > /dev/null 2>&1 ;
      do printf "."; sleep 1; done;
      printf " done!\n"
326 327
    - psql -h db-postgres -U postgres -c 'select version();'
```