R5.07 • Automatisation de la Chaîne de Production Support de cours & Travaux Pratiques

Support principal & Travaux Pratiques

✍️ Florent Pruvost (modifié par Pierre Ramet) • IUT de Bordeaux — BUT Info

Déployer automatiquement ses paquets : release source, paquet Debian, image Docker
- réfléchir aux notions d'intégration continue vs. distribution continue vs. déploiement continu
- discuter du versioning sémantique : https://semver.org/
Déployer automatiquement sa documentation via GitLab Pages (gitlab.com avec miroir ou remote)

Introduction

Vérifiez que vos pipelines sont toujours fonctionnels.

Pour cela, trois prérequis à vérifier :

le jeton d'accès personnel (Personal Access Token) GitLab,
le service gitlab-runner,
le service podman.

Pour avoir accès à votre jeton et à la bonne configuration podman, vous pouvez utiliser le script setenv-podman.sh, commande à taper dans chaque nouveau terminal ou à ajouter dans votre .bashrc :

source ~/setenv-podman.sh
# rappel : un personal access token valide doit se trouver dans le fichier ~/.gitlabtoken

Ensuite, pour lancer le service gitlab-runner :

soit le service est déjà configuré et fonctionnel

systemctl --user status gitlab-runner.service
# répond : active (running)

soit vous le lancez manuellement dans un nouveau terminal

~/gitlab-runner run

Enfin, pour valider que les pipelines fonctionnent, lancez un pipeline. Par exemple manuellement via la page Build -> Pipelines -> Run pipeline, en choisissant la branche 'auto' du projet Heat sur laquelle vous avez déjà travaillé.

Distribuer la dernière version stable

Le processus de développement d'un logiciel implique de faire des releases régulièrement. Par release on entend une version bien identifiée, testée, avec une interface fixée, une documentation, un changelog (document texte rappelant les modifications entre deux versions) et une ou plusieurs archives disponibles pour l'installation.

Le processus de mise à disposition de ces éléments peut être automatisé afin de gagner du temps humain à chaque création d'une nouvelle release. Ainsi cela permet d'en faire plus facilement et donc plus souvent.

Créer une release

À partir de votre branche 'auto', on vous demande de créer une nouvelle release source et binaire de Heat et de la publier sur GitLab.

Manuellement via l'interface web GitLab

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
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 HEAT_VERSION dans le fichier CMakeLists.txt.

Attention. Par soucis de cohérence pour la suite du cours, on va considérer que le format de la version du paquet doit correspondre au format choisit pour le tag Git : ex. v1.0.0. Il sera possible de vérifier le format avec une regex du type :
$HEAT_VERSION =~ /^v[0-9]\.[0-9]\.[0-9]$/
Il faut donc modifier le fichier CMakeLists.txt :
set(HEAT_VERSION "v${HEAT_VERSION_MAJOR}.${HEAT_VERSION_MINOR}.${HEAT_VERSION_PATCH}")

Re-exécutez le bloc précédent pour la création de paquets (les commandes avec rm et cmake) et vérifiez que les paquets sont générés avec la version v1.0.0 :

ll build/heat-v1.0.0*

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

git add CMakeLists.txt
git commit -m "Modification de la variable HEAT_VERSION"
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
- Change version format in CMakeLists.txt

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.

Via l'API GitLab

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.

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

# téléverser heat-v1.0.0-Linux.deb sur le package registry
curl --header "PRIVATE-TOKEN: $TOKEN" --upload-file ./build/heat-$TAG_NAME-Linux.deb "https://gitlab-ce.iut.u-bordeaux.fr/api/v4/projects/$PROJECT_ID/packages/generic/release/$TAG_NAME/heat-$TAG_NAME-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/$TAG_NAME/heat-$TAG_NAME.tar.gz"
wget "https://gitlab-ce.iut.u-bordeaux.fr/api/v4/projects/$PROJECT_ID/packages/generic/release/$TAG_NAME/heat-$TAG_NAME-Linux.deb"
ll heat-$TAG_NAME*
rm heat-$TAG_NAME.tar.gz
rm heat-$TAG_NAME-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/$TAG_NAME/heat-$TAG_NAME.tar.gz"
wget "https://$USER:$TOKEN@gitlab-ce.iut.u-bordeaux.fr/api/v4/projects/$PROJECT_ID/packages/generic/release/$TAG_NAME/heat-$TAG_NAME-Linux.deb"

Admettons que le tag est 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-$TAG_NAME.tar.gz\", \"url\": \"https://gitlab-ce.iut.u-bordeaux.fr/api/v4/projects/$PROJECT_ID/packages/generic/release/$TAG_NAME/heat-$TAG_NAME.tar.gz\" }, \
                                                    { \"name\": \"heat-$TAG_NAME-Linux.deb\", \"url\": \"https://gitlab-ce.iut.u-bordeaux.fr/api/v4/projects/$PROJECT_ID/packages/generic/release/$TAG_NAME/heat-$TAG_NAME-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.

Nous allons maintenant écrire un script ./tools/release.sh afin de créer la release v1.0.0 via l'API GitLab. Il aura comme en-tête (1ère ligne) #!/bin/sh et contiendra le bloc avec l'évaluation de la commande curl ci-dessus pourr créer la release. Testez son fonctionnement :

chmod +x ./tools/release.sh
./tools/release.sh

Sauvegarder le script ./tools/release.sh :

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

Via GitLab-CLI

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.

Distribution en continu

Le but ici est d'automatiser la création et la distribution d'une release dans gitlab-ci.yml.

Lors d'un pipeline, GitLab CI fournit des variables d'environnement contenant des informations : URL du projet Git, référence Git exécutée, jeton GitLab temporaire (CI_JOB_TOKEN), etc. On va donc modifier le script release.sh pour utiliser les variables prédéfinies des pipelines existantes. Remplacer les noms de variables d'environnement dans le script, en respectant la casse :

PRIVATE-TOKEN: $TOKEN -> JOB-TOKEN: $CI_JOB_TOKEN

TAG_NAME -> CI_COMMIT_TAG

PROJECT_ID -> CI_PROJECT_ID

Attention à bien conserver le champ tag_name en minuscule dans la commande curl avec le `–data`.

Dans un premier temps, on va modifier .gitlab-ci.yml pour ajouter un job package qui récupère le cache du job build, génère les packages avec CPack et les téléverser sur le package registry du projet.

package:
  stage: package
  needs: ["build"]
  script:
    - cmake --build build --target package_source
    - cmake --build build --target package
    - |
      for file in build/heat-*.tar.gz build/heat-*.deb; do
        if [ -f "$file" ]; then
          filename=$(basename "$file")
          echo "Upload de $filename vers le registre de paquets..."
          curl --header "JOB-TOKEN: $CI_JOB_TOKEN" --upload-file "$file" \
            "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/release/${CI_COMMIT_TAG}/$filename"
        fi
      done
  cache:
    key: "$CI_COMMIT_REF_SLUG"
    untracked: true
    policy: pull

Dans un second temps on va modifier .gitlab-ci.yml pour ajouter un job release qui va permettre de créer la release automatiquement lorsque l'utilisateur pousse un nouveau tag (en respectant la syntaxe sémantique vX.Y.Z) sur GitLab.

Attention à ne pas oubliez pas d'ajouter les stages package et release dans votre fichier .gitlab-ci.yml :
stages: [buildenv, build, test, package, release]

Deux approches sont possibles pour réaliser la création automatique de la release :

Approche 1 : Script personnalisé avec curl et l'API REST

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

release_curl:
  stage: release
  needs: ["package"]
  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

Approche 2 : Outil officiel natif GitLab release-cli

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_cli:
  stage: release
  image: registry.gitlab.com/gitlab-org/release-cli:latest
  needs: ["package"]
  rules:
    - if: if: $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_TAG =~ /^v[0-9]\.[0-9]\.[0-9]$/
  script:
    - echo "Création de la release pour la version $CI_COMMIT_TAG"
  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"

Cet outil permet de construire une release sans passer par une commmande curl, mais il ne dispense pas de téléverser les packages source et binaire au préalable.

Comparaison Approche curl + API REST Approche native release-cli

Dépendances dans l'image Nécessite `curl`, `jq`, `bash` dans l'image de test Image légère dédiée prête à l'emploi (`release-cli:latest`)

Robustesse syntaxique Concaténation JSON fragile avec quotes échappées Déclaratif en YAML, validé automatiquement par le linter GitLab

Authentification Gestion manuelle de l'en-tête `JOB-TOKEN: $CI_JOB_TOKEN` Intégrée nativement sans en-tête explicite

Pédagogie Formateur pour comprendre les requêtes HTTP/REST Standard industriel actuel des chaînes DevOps GitLab

Comparaison	Approche curl + API REST	Approche native release-cli
Dépendances dans l'image	Nécessite `curl`, `jq`, `bash` dans l'image de test	Image légère dédiée prête à l'emploi (`release-cli:latest`)
Robustesse syntaxique	Concaténation JSON fragile avec quotes échappées	Déclaratif en YAML, validé automatiquement par le linter GitLab
Authentification	Gestion manuelle de l'en-tête `JOB-TOKEN: $CI_JOB_TOKEN`	Intégrée nativement sans en-tête explicite
Pédagogie	Formateur pour comprendre les requêtes HTTP/REST	Standard industriel actuel des chaînes DevOps GitLab

Application sur le projet Heat

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).

RUN apk add  bash curl jq dpkg graphviz

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 (nouveau tag, 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 du tag 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 le tag (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
Vous pouvez également supprimer une release ou un package directement depuis l'interface web de Gitlab.

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

Déploiement en continu

Jusqu'à présent, nous avons pu mettre en œuvre les tests unitaires automatiques (intégration continue) ainsi que la distribution d'une version stable via le processus de release (distribution continue). Pour certaines applications, par exemple des services web, il est en plus nécessaire d'installer la dernière version mise à jour dans son environnement de production : on parle alors de déploiement continu.

Déploiement de son application via Docker

Le fichier Dockerfile sert de recette au déploiement de notre application.

Ajouter un fichier Dockerfile au Git afin d'installer l'application dans l'image docker :

ARG IMAGE_FROM
FROM $IMAGE_FROM
RUN mkdir -p heat/
COPY . heat/
RUN cd heat/ && cmake -B build && cmake --build build
USER root
RUN cd heat/ && cmake --install build && cd /builds && rm -r heat/
USER gitlab

Pour tester localement :

rm build -rf
podman build -t heat -f Dockerfile --build-arg IMAGE_FROM=gitlab-ce.iut.u-bordeaux.fr:5050/$USER/heat/testing .

Remarquez qu'on se base ici sur notre image de test pour éviter la réinstallation de tous les paquets.

Modifier le .gitlab-ci.yml afin d'y ajouter le job de déploiement (ajouter aussi deploy comme dernière étape dans les stages en début de fichier) :

deploy:
  stage: deploy
  rules:
    - if: $CI_PIPELINE_SOURCE == "push"
  dependencies: []
  image: quay.io/podman/stable
  variables:
    IMAGE_TAG: $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG
  before_script:
    - podman login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" $CI_REGISTRY
  script:
    - podman build -t $IMAGE_TAG -f Dockerfile --build-arg IMAGE_FROM=$CI_REGISTRY_IMAGE/testing .
    - podman push $IMAGE_TAG

Notez que le nom de notre image est constitué de la racine de notre registre CI_REGISTRY_IMAGE + le nom de la référence Git (branche, tag) CI_COMMIT_REF_SLUG. On peut ainsi construire des environnements spécifiques par branche.

Note. Le mot-clé dependencies: [] est utilisé pour indiquer qu'on ne souhaite pas télécharger les artefacts des jobs des étapes précédentes puisqu'ils ne sont pas nécessaires ici.

Note. On aurait pu utiliser la même règle rules que pour le job release (tag push), mais on souhaite ici pouvoir déployer l'environnement de production pour chaque évolution dans les branches. Éventuellement, on pourrait déployer seulement sur la branche master et pour des tags, en ajoutant :
- if: $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
- if: $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_TAG

Visiter la page Deploy -> Container Registry et vérifier la présence de votre image de production.

Tester l'image en local :

export TOKEN=`cat ~/.gitlabtoken`
podman login gitlab-ce.iut.u-bordeaux.fr:5050 -u $USER -p $TOKEN
podman run gitlab-ce.iut.u-bordeaux.fr:5050/$USER/heat:auto /usr/local/bin/heat_seq 33 33 33 1 0

Déploiement de la documentation

Un autre exemple courant de déploiement continu est la documentation. On cherche par exemple à maintenir une page de documentation à jour par rapport au code de la branche principale.

Sur le GitLab de l'IUT, la fonctionnalité de Pages (site web de pages HTML/CSS statiques associé au projet Git) n'est pas activée, il faut donc tester cette fonctionnalité sur un autre GitLab.

Créer un compte sur GitLab.com : https://gitlab.com/users/sign_in.
Créer un projet vide (sans README initial) heat.

Dans votre projet Heat local, commencez par pousser la branche master sur le serveur GitLab.com :

export LOGIN="votre login gitlab.com"
git remote add gitlabcom https://gitlab.com/$LOGIN/heat.git
git switch master
git push gitlabcom master

Ensuite, positionnez-vous sur votre branche auto, créez une nouvelle branche pages et ajoutez un script ./tools/pages.sh générant la documentation :

#!/bin/sh

set -x

mkdir public

cmake -B build -DHEAT_DOC=ON
cmake --build build
cp -r build/doc/html public/doxygen

./build/heat_seq 33 33 500 1 0
python3 heat_plot.py
ffmpeg -i heat.avi -c:v libtheora -q:v 7 -c:a libvorbis -q:a 4 heat.ogv

cp tools/index.html public/
cp heat.ogv public/

On pourra utiliser le fichier ./tools/index.html suivant :

<video style="display:block; margin: 0 auto;" width="900" height="900" controls>
  <source src="heat.ogv" type="video/mp4">
  Your browser does not support the video tag.
</video>

See the doxygen documentation <a href=./doxygen/>here</a>.

Modifiez le fichier .gitlab-ci.yml pour y ajouter le job de construction de la documentation :

pages:
  stage: deploy
  image: fpruvost/heat
  needs: [] # Le job s'exécute immédiatement sans attendre les tests (DAG)
  rules:
    - if: $CI_COMMIT_BRANCH == "master" || $CI_COMMIT_BRANCH == "pages"
  artifacts:
    paths:
      - public
  script:
    - ./tools/pages.sh

Par convention, le job doit être nommé exactement pages et les fichiers ajoutés dans les artefacts seront automatiquement téléversés sur le site web associé au projet sur GitLab.com (voir la page Deploy -> Pages).

Pour information, l'image docker fpruvost/heat a été construite avec ce Dockerfile (voir sur Docker Hub) :

FROM ubuntu:24.04

# Installing as root: docker images are usually set up as root.
# Since some autotools scripts might complain about this being unsafe, we set
# FORCE_UNSAFE_CONFIGURE=1 to avoid configure errors.
ENV FORCE_UNSAFE_CONFIGURE=1
ENV DEBIAN_FRONTEND noninteractive

RUN apt-get update -y
RUN apt-get install -y build-essential clang cmake curl doxygen ffmpeg gcovr git python-is-python3 python3-numpy python3-matplotlib xsltproc
RUN apt-get autoremove -y

Commentez les autres jobs (avec un point devant le nom de chaque job) puis testez le job pages en poussant votre branche pages sur GitLab.com :

git add ...
git commit -m ...
git push gitlabcom pages

Dans vos pipelines, un nouveau job pages:deploy sera créé automatiquement et se chargera de la mise à jour du site web avec les nouveaux fichiers.

Vous pouvez maintenant visiter la page de votre site dont l'URL est indiquée sur Deploy -> Pages, quelque chose comme : https://$LOGIN.gitlab.io/heat/.