Utilisation de l'API Gitlab CI/CD

Comme tout bon produit, Gitlab propose une API REST pour contrôler son application. Cela va permettre d'automatiser des tâches répétitives telles que :

• la création et la gestion de groupes et de projets
• de le lier avec d'autres produits de votre infrastructure
• de commiter des fichiers
• gérer des tags
• créer des releases
• de déclencher des pipelines CI
• ...

Authentification à l'API Gitlab

La plupart des requêtes de l'API Gitlab nécessitent une authentification. On peut s'authentifier de plusieurs façons à l'API GitLab:

• tokens OAuth2
• tokens d'accès personnel
• tokens d'accès de projet
• Cookie de Session
• token de job (limiter à certains endpoint)

Je ne vais documenter que le token d'accès de projet. Pour les autres je vous renvoie à la documentation de l'api

Authentification par jetons de projets

Ma préférence va à ce type de token car il ne sont pas lié à un compte utilisateur. Pour créer un token d'accès de projet il suffit de se rendre dans settings/Access Tokens.

On peut :

• limiter les accès à la lecture et/ou l'écriture
• limiter dans le temps
• de les révoquer

Une fois le token créé bien le stocker car il ne sera plus possible de le récupérer.

Ils peuvent être utilisé de deux façons:

• soit dans l'entete curl "https://gitlab.example.com/api/v4/projects?private_token=<your_access_token>"
• soit dans le header curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects"

Les différentes ressources de l'API Gitlab

Je ne vais pas vous faire la liste complète des ressources accessibles depuis l'API car les possibilités sont immenses. Le plus simple est de vous rendre sur la documentation des ressources de l'api

Je vous présenter quelques exemples.

Déclencher un pipeline par API

Il est possible de déclencher des pipelines CI via l'API. Pour cela il suffit de se rendre dans le menu project settings / CI/CD / Pipeline triggers.

Vous remarquerez que tout est documenté. La commande curl, le script à intégrer dans le fichier de ci, le webhook.

Pour exemple pour démarrer le ci avec curl il suffit de rentrer cette commande :

curl -X POST \
     -F token=TOKEN \
     -F ref=REF_NAME \
     https://gitlab.com/api/v4/projects/16138477/trigger/pipeline

Commit par API

Voyons un autre exemple d'utilisation de l'api. Je l'utilise dans le cadre de la création d'une documentation d'API. Cet API ne donne l'accès au fichier swagger.json que lorsqu elle est démarrée. Donc dans un CI je build puis déploie l'API et dans une autre action je récupère son fichier swagger que je commit dans un autre projet qui construit une documentation versionnée.

Personnellement je préfère la version avec form plus simple à écrire.

curl --request POST \
      --form "branch=master" \
      --form "start_branch=master" \
      --form "commit_message=test_push_file_from_api" \
      --form "actions[][action]=update" \
      --form "actions[][file_path]=path/file.json" \
      --form "actions[][content]=<file.json" \
      --header "PRIVATE-TOKEN: xxxxxxxxxxxxxxxx" \
      "https://gitlab.com/api/v4/projects/23/repository/commits"

Il est possible d'ajouter (create), de détruire (delete), de déplacer (move), de mettre à jour (update) plusieurs fichiers dans un seul commit. On peut aussi changer les permissions d'un fichier. Pour cela il suffit d'ajouter autant d'action que nécessaires:

curl --request POST \
     --form "branch=master" \
     --form "commit_message=some commit message" \
     --form "start_branch=master" \
     --form "actions[][action]=create" \
     --form "actions[][file_path]=foo/bar" \
     --form "actions[][content]=</path/to/local.file" \
     --form "actions[][action]=delete" \
     --form "actions[][file_path]=foo/bar2" \
     --form "actions[][action]=move" \
     --form "actions[][file_path]=foo/bar3" \
     --form "actions[][previous_path]=foo/bar4" \
     --form "actions[][content]=</path/to/local1.file" \
     --form "actions[][action]=update" \
     --form "actions[][file_path]=foo/bar5" \
     --form "actions[][content]=</path/to/local2.file" \
     --form "actions[][action]=chmod" \
     --form "actions[][file_path]=foo/bar5" \
     --form "actions[][execute_filemode]=true" \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/projects/1/repository/commits"

Gestion des tags

Il est possible de créer (POST) et détruire (DELETE) des tags par API. Je l'utilise également pour le versioning de ma documentation avec sphinx.

Création d'un tag

curl --request POST \
     --header "PRIVATE-TOKEN: <your_access_token>"
     "https://gitlab.example.com/api/v4/projects/5/repository/tags?tag_name=test&ref=master"

Destruction d'un tag

curl --request POST \
     --header "PRIVATE-TOKEN: <your_access_token>"
     "https://gitlab.example.com/api/v4/projects/5/repository/tags/tag_name"

Création d'une release via l'API Gitlab

Dans un autre billet je vous expliquais comment créer une release gitlab via un appel à l'api depuis un script d'un job CI:

curl --data "{
        \"tag_name\": \"${TAG}\",
        \"name\": \"${TAG}\",
        \"ref\": \"${CI_COMMIT_SHORT_SHA}\",
        \"description\": \"## CHANGELOG\r\n\r\n- Remove limit of 100 when searching \",
        \"assets\": {
            \"links\": [
              {
                \"name\": \"binaries.${TAG}.tar.gz\",
                \"url\": \"https://myrepo/repository/repo1/binaries.${TAG}.tar.gz\",
                \"filepath\": \"/binary\",
                \"link_type\":\"package\"
              }
            ]
          }
        }" \
        --header "Content-Type: application/json" \
        --header "Private-Token: ${PRIVATE_TOKEN}" \
        --request POST "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/releases"

Conclusion

La liste des possibles est immense et le travail aussi. Vous pouvez tout imaginer. Un autre exemple