Mise à jour : 9 juillet 2025
Lecture : 10 min
Automatisez vos sorties et notes de version avec GitLab
Découvrez comment automatiser vos livraisons de logiciels avec l'API Changelog de GitLab : créez des artefacts, changelogs complets et notes de version clairs.
Mise à jour 2025 : l'API Changelog de GitLab continue d'évoluer et offre désormais de nouvelles fonctionnalités avancées, telles que la génération de changelogs personnalisés basés sur l'historique de vos commits. Ces nouveautés ne sont pas détaillées dans cet article, mais vous pouvez les consulter dans notre documentation officielle dédiée aux changelogs.
Lorsque vous développez un logiciel dont les utilisateurs se servent au quotidien, il est essentiel de les informer des modifications apportées à chaque nouvelle version (nouvelles fonctionnalités, modifications ou suppressions). Ils peuvent ainsi tirer pleinement parti du logiciel et éviter les mauvaises surprises lors des mises à niveau.
Mais historiquement, rédiger les notes de version et maintenir un changelog ont toujours été des tâches laborieuses qui obligent les équipes et les Release Managers à passer au crible les modifications et l'historique des merge requests. Désormais, avec l'API Changelog de GitLab, vous pouvez tirer parti de l'historique détaillé des modifications enregistrées dans votre dépôt Git pour créer automatiquement des notes de version et tenir à jour votre changelog.
Découvrez dans ce tutoriel comment intégrer cette automatisation dans vos pipelines CI/CD.
Sorties de nouvelles versions dans GitLab
Dans GitLab, une nouvelle version correspond à une version spécifique de votre code, identifiée par un tag git. Elle regroupe les modifications apportées depuis la dernière version, les notes de version associées, ainsi que tous les artefacts générés à partir de cette version du code, tels que les images Docker, les paquets d'installation et la documentation.
Vous pouvez créer et suivre les sorties de ces nouvelles versions dans GitLab à l'aide de l'interface utilisateur en appelant notre API Release ou en définissant un job de release dans un pipeline CI. Nous utiliserons ce dernier dans ce tutoriel afin de bénéficier de l'automatisation déjà en place pour les tests, les scans du code et les autres étapes de validation, et d'automatiser également les sorties de nouvelles versions.
Nous devons d'abord disposer d'un historique clair de toutes les modifications apportées. C'est ce que fournit précisément le dépôt Git via les messages de commit et le suivi des merge requests. Ce dernier garantit une génération automatisée et fiable des notes de version et du changelog.
Lignes terminales dans un commit
Les lignes terminales dans un commit Git sont des métadonnées structurées ajoutées en fin de vos messages de commit, sous la forme simple <HEADER>:<BODY>. L'interface de ligne de commande git peut ensuite les analyser et les extraire pour les utiliser dans d'autres systèmes, par exemple via la commande git commit --sign-off qui permet de confirmer un commit en y ajoutant une ligne terminale Signed-off-by: <Votre nom>. Vous pouvez y ajouter n'importe quelle information structurée. Il s'agit donc d'un emplacement idéal pour stocker des métadonnées, et dans notre exemple, pour générer automatiquement notre changelog.
En ajoutant la ligne terminale Changelog: <added/changed/removed> à la fin de nos messages de commit, l'API Changelog de GitLab l'analysera et créera automatiquement un changelog.
Nous allons illustrer ce mécanisme en apportant quelques modifications à un code source existant afin de sortir une nouvelle version et de générer automatiquement ses notes de version et les entrées du changelog correspondant.
Exemple concret avec une application Python
Partons d'un dépôt contenant une application web simple écrite en Python. Supposons que la version 1.0.0 de cette application vient de sortir et représente l'état actuel du code, et qu'elle a été créée manuellement dans GitLab, sans pipeline de sortie de nouvelle version automatisé :
Modifications en vue de la version 2.0.0
Comme nous sommes en mode de développement rapide, nous allons travailler sur la sortie de la version 2.0.0 de notre application dès aujourd'hui. Celle-ci introduira une fonctionnalité de chatbot et supprimera la fonctionnalité de blockchain quantique, qui servait uniquement à impressionner les investisseurs lors de notre premier cycle de financement par capital-risque. Nous allons également ajouter un job de sortie de nouvelle version automatisé à notre pipeline CI/CD.
Tout d'abord, nous devons supprimer les fonctionnalités obsolètes à l'aide d'une merge request qui contient les suppressions nécessaires en veillant à ce que le message de commit inclue la ligne terminale Changelog: removed. Pour cela, nous pouvons par exemple l'inclure directement dans un commit, ou effectuer un rebasage interactif et l'ajouter à l'aide de l'interface de ligne de commande (CLI).
Mais dans notre exemple, nous traiterons cette étape en dernier, et utiliserons plutôt le bouton Modifier le message de commit dans GitLab pour ajouter la ligne terminale au commit comme suit :
Vous pouvez également modifier le titre du commit pour qu'il soit plus concis. Nous allons donc renommer notre commit « Supprimer les fonctionnalités inutilisées », pour que ce titre apparaisse dans le changelog.
Ensuite, ajoutons de nouvelles fonctionnalités pour la version 2.0.0. Là encore, il suffit d'ouvrir une autre merge request qui inclut nos nouvelles fonctionnalités, de modifier le commit pour inclure la ligne terminale Changelog: added, puis de modifier son titre pour qu'il soit plus concis :
Nous sommes maintenant prêts à publier la version 2.0.0. Mais cette fois-ci, au lieu de la créer manuellement, nous allons ajouter les jobs nécessaires à notre fichier .gitlab-ci.yml : ils gèreront automatiquement la sortie de la nouvelle version à notre place et généreront les notes de version et les entrées du changelog lorsque nous ajouterons à notre code le tag 2.0.0 en référence à la nouvelle version.
Remarque : pour ajouter facilement des lignes terminales de changelog, utilisez un outil comme Danger, qui permet de vérifier automatiquement le respect des conventions dans les merge requests.
Création d'un pipeline automatisé de sortie de nouvelle version
La première étape consiste à créer un token d'accès au projet qui nous permettra d'appeler l'API de GitLab afin de générer les entrées de notre changelog. Créons un token d'accès au projet avec la portée de l'API, puis stockons-le dans les variables CI/CD du projet sous le nom CI_API_JETON. Nous référencerons cette variable à des fins d'authentification auprès de l'API.
Ensuite, ajoutons deux nouveaux jobs à notre fichier gitlab-ci.yml :
prepare_job:
stage: prepare
image: alpine:latest
rules:
- if: '$CI_COMMIT_TAG =~ /^v?\d+\.\d+\.\d+$/'
script:
- apk add curl jq
- 'curl -H "PRIVATE-TOKEN: $CI_API_TOKEN" "$CI_API_V4_URL/projects/$CI_PROJECT_ID/repository/changelog?version=$CI_COMMIT_TAG" | jq -r .notes > release_notes.md'
artifacts:
paths:
- release_notes.md
release_job:
stage: release
image: registry.gitlab.com/gitlab-org/release-cli:latest
needs:
- job: prepare_job
artifacts: true
rules:
- if: '$CI_COMMIT_TAG =~ /^v?\d+\.\d+\.\d+$/'
script:
- echo "Creating release"
release:
name: 'Release $CI_COMMIT_TAG'
description: release_notes.md
tag_name: '$CI_COMMIT_TAG'
ref: '$CI_COMMIT_SHA'
assets:
links:
- name: 'Container Image $CI_COMMIT_TAG'
url: "https://$CI_REGISTRE_IMAGE/$CI_COMMIT_REF_SLUG:$CI_COMMIT_SHA"
Dans notre configuration, le job prepare_job utilise curl et jq pour appeler le point de terminaison de l'API Changelog de GitLab, puis transmet le résultat à notre job release_job chargé de créer automatiquement la nouvelle version.
Voici les principaux éléments à retenir :
-
Nous utilisons le token d'accès au projet créé précédemment pour appeler l'API Changelog de GitLab, qui génère les notes de version que nous stockons en tant qu'artefact.
-
Nous utilisons la variable
$CI_COMMIT_TAGpour identifier la version. Pour que l'API Changelog fonctionne correctement, nous devons utiliser la gestion sémantique de version pour nos tags (par exemple,2.0.0). Nous avons également restreint le job de sortie de nouvelle version à l'aide d'une règle spécifique dans la sectionrules, qui vérifie la présence d'un tag de version sémantique.- La gestion sémantique de version est nécessaire pour que l'API Changelog de GitLab déclenche le job. Elle utilise ce format pour trouver la version la plus récente à comparer à notre version actuelle.
-
Nous utilisons l'image
release-cliofficielle de GitLab, indispensable pour exploiter le termereleasedans un job. -
Nous utilisons le terme
releasepour créer une sortie de nouvelle version dans GitLab et pour le remplissage des champs obligatoires. -
Nous pouvons transmettre un fichier en tant qu'argument pour la
descriptionde la nouvelle version. Dans notre exemple, il s'agit du fichier que nous avons généré lors du jobprepare_job, puis transmis à ce job sous forme d'artefact. -
Nous avons également inclus notre image de conteneur, qui a été compilée plus tôt dans le pipeline, en tant que ressource associée à la nouvelle version. Vous pouvez également y joindre les ressources de votre choix, générées lors de votre processus de compilation, telles que des binaires ou de la documentation, à condition de fournir l'URL redirigeant vers l'endroit où vous les avez chargés plus tôt dans le pipeline.
Automatisation d'une sortie de nouvelle version
Avec cette configuration, il suffit d'effectuer le push d'un tag respectant notre schéma de gestion des versions vers notre dépôt à l'aide de la CLI ou comme dans notre exemple, directement depuis l'interface utilisateur de GitLab, sur la branche principale, en sélectionnant Code -> Tags -> Nouveau tag dans la barre latérale :
Dès la création du tag, nos pipelines commenceront à s'exécuter automatiquement. L'API Changelog de GitLab génère alors des notes de version au format markdown contenant toutes les modifications apportées entre cette version et la version précédente.
Voici un extrait du markdown généré dans notre exemple :
## 2.0.0 (2023-08-25)
### added (1 change)
- [Add ChatBot](gl-demo-ultimate-bridley/super-devsecops-incorporated/simply-notes-release-demo@0c3601a45af617c5481322bfce4d71db1f911b02) ([merge request](gl-demo-ultimate-bridley/super-devsecops-incorporated/simply-notes-release-demo!4))
### removed (1 change)
- [Remove Unused Features](gl-demo-ultimate-bridley/super-devsecops-incorporated/simply-notes-release-demo@463d453c5ae0f4fc611ea969e5442e3298bf0d8a) ([merge request](gl-demo-ultimate-bridley/super-devsecops-incorporated/simply-notes-release-demo!3))
Comme vous pouvez le constater, GitLab a extrait automatiquement les entrées de nos notes de version à l'aide des lignes terminales que nous avons intégrées dans nos messages de commit Git. De plus, des notes incluent des liens vers la merge request associée pour accéder rapidement aux compléments d'information et discussions relatifs aux modifications.
Voici notre nouvelle version 2.0.0 :
Automatisation de la mise à jour du changelog
Pour maintenir à jour votre changelog (soit l'historique rassemblant toutes vos notes de version), vous pouvez effectuer une requête POST vers le point de terminaison de l'API Changelog utilisé précédemment.
Si vous effectuez cette opération dans le cadre de votre pipeline de nouvelle version, intégrez cette étape en ajoutant ce qui suit à la section script de votre job de préparation :
'curl -H "PRIVATE-TOKEN: $CI_API_TOKEN" -X POST "$CI_API_V4_URL/projects/$CI_PROJECT_ID/repository/changelog?version=$CI_COMMIT_TAG"
Notez que cette opération modifie le dépôt en créant un commit qui ajoute les notes de la nouvelle version à un fichier CHANGELOG.md :
Et voilà, nous avons terminé ! En utilisant l'historique détaillé fourni par git avec quelques lignes terminales de commit pratiques, nous pouvons tirer parti de la puissante de l'API et des pipelines CI/CD de GitLab pour automatiser notre processus de sortie de nouvelle version et de génération de notes de version.
Pour découvrir le projet utilisé dans ce tutoriel, consultez ce lien.