Déploiement continu

Pour cela, commencez par générer une archive source. CMake utilise CPack pour faciliter la création de packages source et binaires. Utilisez par exemple ces commandes pour générer les archives source et binaire (compatible Debian) :

rm -r build
cmake -S . -B build -DHEAT_DOC=ON
cmake --build build --target doc
cp -r build/doc/html doc/
cmake --build build --target package_source # génère build/heat-1.0.0.tar.gz
cmake --build build --target package # génère build/heat-1.0.0-Linux.deb

Petit rappel concernant l'utilisation de CMake ici.

Pour information, la version du paquet, ici 1.0.0, est définie par la variable CMake HEAT_VERSION dans le fichier CMakeLists.txt. Remarquez que l'on génère la documentation afin de l'incorporer dans l'archive source.

Sauvegardez les 6 lignes précédentes de création de paquets (les commandes avec rm, cmake, cp) dans un script ./tools/release.sh avec comme en-tête (1re ligne) #!/bin/sh. Testez son fonctionnement :

chmod +x ./tools/release.sh
./tools/release.sh
ll build/heat-1.0.0*

Maintenant, sauvegardez votre état actuel via un tag Git, ex. v1.0.0 :

git add ./tools/release.sh
git commit -m "Ajout script release.sh"
git tag v1.0.0
git push origin --tags

Visitez ensuite la page Code -> Tags de votre projet et vérifiez que vous trouvez bien votre tag v1.0.0. Le tag Git permet d'identifier cette version au sens Git et donc de retrouver cette version précise du code source avec git checkout v1.0.0. Utilisez git checkout auto (ou git switch auto) pour revenir sur votre branche auto.

Sur la page des tags, vous pouvez créer manuellement une release au sens GitLab à partir d'un tag existant. Cliquez sur 'Create release' à droite, puis ajoutez quelques commentaires dans la section `Release notes` :

- Add .gitlab-ci.yml to use pipelines
- Use a dockerfile-testing file to define the testing environment

Vous pouvez ajouter des liens de type URL et des fichiers attachés. Utilisez le bouton "Attach a file or image" (trombone dans la partie Release notes) afin d'y ajouter les fichiers .tar.gz et .deb que vous venez de générer avec CPack. Sauvegarder. Vous avez une nouvelle release sur la page Deploy -> Releases avec le code source téléchargeable ainsi que vos deux paquets associés.

La création de release GitLab peut être effectuée via une commande curl afin d'interagir avec l'API REST de GitLab, l'opération peut ainsi être scriptable et, nous le verrons par la suite, automatisable.

Lors du TP précédent, vous aviez créé un Personal Access Token sauvegardé dans le fichier ~/.gitlabtoken. Ce jeton vous permet d'exécuter des commandes pour interagir avec GitLab et de réaliser des opérations sur vos projets.

Exemple pour interroger GitLab sur la liste des membres d'un projet spécifique. Le projet est identifiable via son numéro identifiant unique que l'on trouve sur la page principale (cf. "Project ID", trois petits points verticaux en haut à droite, à côté de Star et Fork) :

export TOKEN=`cat ~/.gitlabtoken`
export PROJECT_ID="votre numéro de projet"
curl --header "PRIVATE-TOKEN: $TOKEN" "https://gitlab-ce.iut.u-bordeaux.fr/api/v4/projects/$PROJECT_ID/users"

# sortie json structurée
curl --header "PRIVATE-TOKEN: $TOKEN" "https://gitlab-ce.iut.u-bordeaux.fr/api/v4/projects/$PROJECT_ID/users" | jq

Vous pouvez accéder à l'API sur les releases (lister, créer, supprimer) :

# afficher les releases existantes
curl --header "PRIVATE-TOKEN: $TOKEN" "https://gitlab-ce.iut.u-bordeaux.fr/api/v4/projects/$PROJECT_ID/releases" | jq

# afficher leurs noms
curl --header "PRIVATE-TOKEN: $TOKEN" "https://gitlab-ce.iut.u-bordeaux.fr/api/v4/projects/$PROJECT_ID/releases" | jq '.[0].name'

# supprimer la release v1.0.0
export TAG_NAME=v1.0.0
curl --header "PRIVATE-TOKEN: $TOKEN" --request DELETE "https://gitlab-ce.iut.u-bordeaux.fr/api/v4/projects/$PROJECT_ID/releases/$TAG_NAME" | jq

Activer le Package Registry : Settings -> General -> Visibility, project features -> Package registry -> enable and save changes.

Vous pouvez maintenant téléverser des fichiers de type paquets binaires via l'API du Generic Package Repository. Vous pouvez visiter la page Deploy -> Package Registry et y voir vos paquets. Vous pouvez aussi les supprimer à la main.

RELEASE_NUM=`echo $TAG_NAME | sed -e "s#v##"`
# téléverser heat-1.0.0.tar.gz sur le package registry
curl --header "PRIVATE-TOKEN: $TOKEN" --upload-file ./build/heat-$RELEASE_NUM.tar.gz "https://gitlab-ce.iut.u-bordeaux.fr/api/v4/projects/$PROJECT_ID/packages/generic/release/$RELEASE_NUM/heat-$RELEASE_NUM.tar.gz" | jq

# téléverser heat-1.0.0-Linux.deb sur le package registry
curl --header "PRIVATE-TOKEN: $TOKEN" --upload-file ./build/heat-$RELEASE_NUM-Linux.deb "https://gitlab-ce.iut.u-bordeaux.fr/api/v4/projects/$PROJECT_ID/packages/generic/release/$RELEASE_NUM/heat-$RELEASE_NUM-Linux.deb" | jq

# pour retrouver l'id du package
# PACKAGE_ID=`curl --header "PRIVATE-TOKEN: $TOKEN" "https://gitlab-ce.iut.u-bordeaux.fr/api/v4/projects/$PROJECT_ID/packages" | jq '.[0].id'`
# echo $PACKAGE_ID

# pour supprimer le package à partir de id (ne pas le faire, car on va avoir besoin de ce package)
# curl --header "PRIVATE-TOKEN: $TOKEN" --request DELETE "https://gitlab-ce.iut.u-bordeaux.fr/api/v4/projects/$PROJECT_ID/packages/$PACKAGE_ID"

Vous pouvez les télécharger ensuite simplement via wget :

wget "https://gitlab-ce.iut.u-bordeaux.fr/api/v4/projects/$PROJECT_ID/packages/generic/release/$RELEASE_NUM/heat-$RELEASE_NUM.tar.gz"
wget "https://gitlab-ce.iut.u-bordeaux.fr/api/v4/projects/$PROJECT_ID/packages/generic/release/$RELEASE_NUM/heat-$RELEASE_NUM-Linux.deb"
ll heat-$RELEASE_NUM*
rm heat-$RELEASE_NUM.tar.gz
rm heat-$RELEASE_NUM-Linux.deb

Si vous n'avez pas coché la case "Allow anyone to pull from package registry" dans les Settings -> General -> Permissions, il faudra ajouter l'authentification pour pouvoir télécharger les paquets :

wget "https://$USER:$TOKEN@gitlab-ce.iut.u-bordeaux.fr/api/v4/projects/$PROJECT_ID/packages/generic/release/$RELEASE_NUM/heat-$RELEASE_NUM.tar.gz"
wget "https://$USER:$TOKEN@gitlab-ce.iut.u-bordeaux.fr/api/v4/projects/$PROJECT_ID/packages/generic/release/$RELEASE_NUM/heat-$RELEASE_NUM-Linux.deb"

Admettons que le tag est bien déjà créé et que les fichiers sont téléversés sur le package registry, nous allons maintenant procéder à la création de la release finale via l'API :

CMD=`echo curl --header \"Content-Type: application/json\" \
               --header \"PRIVATE-TOKEN: $TOKEN\" \
               --data \'{ \"name\": \"$TAG_NAME\", \"tag_name\": \"$TAG_NAME\", \
                          \"assets\": { \"links\": [{ \"name\": \"heat-$RELEASE_NUM.tar.gz\", \"url\": \"https://gitlab-ce.iut.u-bordeaux.fr/api/v4/projects/$PROJECT_ID/packages/generic/release/$RELEASE_NUM/heat-$RELEASE_NUM.tar.gz\" }, \
                                                    { \"name\": \"heat-$RELEASE_NUM-Linux.deb\", \"url\": \"https://gitlab-ce.iut.u-bordeaux.fr/api/v4/projects/$PROJECT_ID/packages/generic/release/$RELEASE_NUM/heat-$RELEASE_NUM-Linux.deb\" }] } \
                        }\' \
               --request POST \"https://gitlab-ce.iut.u-bordeaux.fr/api/v4/projects/$PROJECT_ID/releases\"`
eval $CMD | jq

Vous pouvez visiter la page Deploy -> Releases.

Modifiez maintenant le script release.sh afin de créer la release v1.0.0 via l'API GitLab en y ajoutant les commandes pour :

1. téléverser les fichiers de packages et
2. créer la release dans la foulée avec l'évaluation de la commande curl ci-dessus.

Sauvegarder le script ./tools/release.sh :

git commit ./tools/release.sh -m "release.sh: publication packages et release"
git push

GitLab-CLI (glab) est un outil en ligne de commande pour GitLab. Il s'intègre dans votre terminal sans avoir à jongler entre les fenêtres et les onglets de votre navigateur. Il permet par exemple de créer, gérer et supprimer des releases.

Pour disposer de cet outil, vous pouvez utiliser l'image docker officielle, disponible aussi sur le registre de l'Université de Bordeaux :

podman pull registry.u-bordeaux.fr/tthor/glab:latest

Pour utiliser glab, il faut d'abord le configurer pour qu'il puisse se connecter à l'instance GitLab de l'IUT. Voici un template à adapter à votre configuration et à placer dans le fichier ~/.config/glab-cli/config.yml :

# Default GitLab hostname to use.
host: gitlab-ce.iut.u-bordeaux.fr
# Allow glab to automatically check for updates and notify you when there are new updates.
check_update: true
# Configuration specific for GitLab instances.
hosts:
    gitlab-ce.iut.u-bordeaux.fr:
	user: __MON_LOGIN_GITLAB_IUT__
	token: __MON_TOKEN_GITLAB_IUT__
	container_registry_domains: gitlab-ce.iut.u-bordeaux.fr,gitlab-ce.iut.u-bordeaux.fr:443,registry.gitlab-ce.iut.u-bordeaux.fr
	api_host: gitlab-ce.iut.u-bordeaux.fr
	git_protocol: ssh
	api_protocol: https

Il faudra aussi modifier les droits par défaut de ce fichier :

chmod 600 ~/.config/glab-cli/config.yml

Vous pouvez télécharger le template config-glab.yml.

On vous recommande ensuite de créer une fonction et un alias pour lancer glab dans un conteneur podman :

function do-glab {
  podman run --rm -it -v ~/.config/glab-cli:/root/.config/glab-cli registry.u-bordeaux.fr/tthor/glab:latest glab $@
}

alias glab="do-glab"

Pour disposer de cet alias, vous pouvez utiliser le script config-glab.sh de la manière suivante :

source config-glab.sh

Vous pouvez maintenant tester glab en listant les releases de votre projet avec :

glab release list -R $USER/heat

Vous pouvez ensuite essayer la création d'une release (après avoir supprimé l'une des versions existantes) en suivant les options détaillées dans cette documentation.

C'est l'approche que nous avons mise en place avec le script release.sh :

release_curl:
  stage: release
  rules:
    - if: $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_TAG =~ /^v[0-9]\.[0-9]\.[0-9]$/
  artifacts:
    name: "$CI_JOB_NAME-$CI_COMMIT_REF_SLUG"
    paths:
      - build/heat-*.tar.gz
      - build/heat-*.deb
  script:
    - ./tools/release.sh

GitLab fournit désormais une image officielle et un mot-clé dédié release: dans le fichier .gitlab-ci.yml via l'outil release-cli. Cette approche est plus déclarative, plus sécurisée et évite d'avoir à manipuler manuellement des chaînes JSON complexes avec curl et jq :

release:
  stage: release
  image: registry.gitlab.com/gitlab-org/release-cli:latest
  rules:
    - if: $CI_COMMIT_TAG =~ /^v[0-9]\.[0-9]\.[0-9]$/
  # Le mot-clé needs permet d'exécuter ce job dès que le job de build est terminé (DAG)
  needs:
    - job: build
      artifacts: true
  script:
    - echo "Création de la release $CI_COMMIT_TAG avec release-cli"
  release:
    tag_name: $CI_COMMIT_TAG
    description: 'Release automatique générée par GitLab CI pour $CI_COMMIT_TAG'
    assets:
      links:
	- name: "heat-$CI_COMMIT_TAG.tar.gz"
	  url: "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/release/${CI_COMMIT_TAG}/heat-${CI_COMMIT_TAG}.tar.gz"
	- name: "heat-$CI_COMMIT_TAG-Linux.deb"
	  url: "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/release/${CI_COMMIT_TAG}/heat-${CI_COMMIT_TAG}-Linux.deb"

Par défaut, GitLab CI exécute les stages de façon strictement séquentielle : tous les jobs du stage `test` doivent être terminés avant que le moindre job du stage `release` ou `deploy` ne démarre.

Le mot-clé needs: permet de briser cette dépendance rigide en définissant un graphe orienté acyclique :

• Un job peut démarrer dès que les jobs listés dans son `needs:` sont validés, sans attendre les autres jobs du même stage.
• Si un job n'a besoin d'aucun artefact préalable (ex. déploiement d'une documentation statique ou linter rapide), on peut spécifier needs: [] pour qu'il s'exécute immédiatement dès le début du pipeline !

Modifier le fichier dockerfile-testing afin d'ajouter les paquets bash curl jq dpkg graphviz (dépendances nécessaires pour la création de l'archive).

Utiliser la règle suivante dans le job buildenv à la place de vos anciennes expérimentations (only: changes, when: manual, only: schedule). Commiter, pousser sur la branche auto. Cela devrait reconstruire l'image de test, tout en évitant de reconstruire l'image pour d'autres scénarios (nouvelle étiquette, pipeline manuel, schedule) :

rules:
  - if: $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_TAG == null
    changes:
      paths:
        - dockerfile-testing

Modifier le numéro de version dans le CMakeLists.txt afin d'être à 1.1.0 :

set(HEAT_VERSION_MAJOR "1")
set(HEAT_VERSION_MINOR "1")
set(HEAT_VERSION_PATCH "0")

Commiter et pousser :

git add -u
git commit -m "Release v1.1.0"
git push

Tester à présent la création d'une étiquette et la pousser sur GitLab :

git tag v1.1.0
git push origin --tags

Si cela ne fonctionne pas, après avoir analysé les logs du job en échec, vous pouvez supprimer l'étiquette (en local et sur le serveur), puis modifier vos sources, commiter, pousser pour retester la procédure :

git tag -d v1.1.0
git push --delete origin v1.1.0
git tag v1.1.0
git push origin --tags

Ne pas hésiter à lire ceci à propos du versioning des releases : https://semver.org/.

Pour garantir que le numéro de tag est cohérent avec le numéro de version du projet, cf. HEAT_VERSION dans le CMakeLists.txt principal qui donne la version aux fichiers générés .tar.gz/.deb, on peut ajouter ces lignes dans release.sh avant de téléverser les archives .tar.gz/.deb avec curl :

PACKAGE=`ls build/heat-*.tar.gz`
PACKAGE_NUM=`echo $PACKAGE | grep -o "[0-9].[0-9].[0-9]"`
if [ $PACKAGE_NUM != $RELEASE_NUM ]; then
  echo "PACKAGE=$PACKAGE"
  echo "PACKAGE_NUM=$PACKAGE_NUM"
  echo "RELEASE_NUM=$RELEASE_NUM"
  echo "(CI_COMMIT_TAG=$CI_COMMIT_TAG)"
  echo "Package number does not match RELEASE_NUM (computed from CI_COMMIT_TAG, without v), exit"
  exit 1
fi