Aktualisiert am: 5. Juni 2025
9 Minuten Lesezeit
GitLab-Tutorial: Releases & Versionshinweise automatisieren
Mit GitLab kannst du Release-Artefakte, Versionshinweise und Änderungsprotokolle, die benutzerbezogenen Software-Änderungen enthalten, automatisieren.
Update 2025 - Die Änderungsprotokoll-API wurde weiterentwickelt und enthält jetzt geniale neue Funktionen, auf die wir in diesem Blog nicht eingehen, wie die Möglichkeit, benutzerdefinierte Änderungsprotokolle mit Vorlagenwerten aus deinem Commit-Verlauf bereitzustellen. Mehr dazu erfährst du in der offiziellen Dokumentation zu Änderungsprotokollen (nur in englischer Sprache verfügbar).
Wenn du Software entwickelst, auf die sich Benutzer(innen) verlassen, ist eine effektive Kommunikation über Änderungen bei jeder Release unerlässlich. Indem du Benutzer(innen) über neue Funktionen sowie darüber informierst, was geändert oder entfernt wurde, stellst du sicher, dass sie die Vorteile der Software wirklich nutzen können und sie bei Upgrades keine unangenehmen Überraschungen erwarten.
In der Vergangenheit war das Erstellen von Versionshinweisen und die Pflege eines Änderungsprotokolls eine mühsame Aufgabe, bei der Entwickler(innen) die Änderungen extern überwachen oder eigene Release Manager den Verlauf der Zusammenführungen durcharbeiten mussten. Mit der Änderungsprotokoll-API von GitLab kannst du den umfassenden Verlauf, der in unserem Git-Repository gespeichert ist, heranziehen, um ganz einfach Versionshinweise zu erstellen und ein Änderungsprotokoll zu führen.
In diesem Tutorial sehen wir uns an, wie du Releases mit GitLab automatisieren kannst und finden heraus, wie man Release-Artefakte, Versionshinweise und ein umfassendes Änderungsprotokoll, das alle benutzerbezogenen Software-Änderungen enthält, erstellt.
Releases in GitLab
Zuerst wollen wir uns ansehen, wie Releases in GitLab funktionieren.
In GitLab ist eine Release eine bestimmte Version deines Codes, die durch ein Git-Tag identifiziert wird. Dieses enthält Details zu den Änderungen seit der letzten Release (und Versionshinweise) sowie zugehörige Artefakte, die aus dieser Version des Codes erstellt wurden, wie Docker-Images, Installationspakete und Dokumentation.
Du kannst Releases in GitLab über die UI erstellen und nachverfolgen, indem du unsere Release-API aufrufst oder den Job release innerhalb einer CI-Pipeline aufrufst. In diesem Tutorial verwenden wir den Job release in einer CI/CD-Pipeline, sodass wir die Automatisierung, die wir in unserer Pipeline zum Testen, für Code-Scans und mehr verwenden, auch für automatisierte Releases nutzen können.
Um unsere Releases zu automatisieren, müssen wir zunächst die folgende Frage beantworten: Wo bekommen wir für unsere Versionshinweise und unser Änderungsprotokoll Informationen zu den vorgenommenen Änderungen? Die Antwort: In unserem Git-Repository, in dem wir durch Commit-Nachrichten und den Merge-Commit-Verlauf eine umfassende Übersicht über die Entwicklungsaktivitäten haben. Sehen wir uns an, ob wir diesen umfassenden Verlauf nutzen können, um automatisch unsere Versionshinweise und Änderungsprotokolle zu erstellen.
Einführung in Commit-Trailer
Commit-Trailer sind strukturierte Einträge in deinen Git-Commits, die erstellt werden, indem du einfach die Formatierungsnachrichten <HEADER>:<BODY> am Ende deines Commits einfügst. Das CLI-Tool git kann diese dann parsen und für die Verwendung in anderen Systemen extrahieren. Ein Beispiel, das du vielleicht schon einmal verwendet hast, ist git commit --sign-off, um ein Commit zu beenden. Dies wird implementiert, indem der Trailer Signed-off-by: <Dein Name> zum Commit hinzugefügt wird. Wir können hier beliebige strukturierte Daten hinzufügen, sodass dies eine tolle Möglichkeit ist, Informationen zu speichern, die für das Änderungsprotokoll nützlich sein könnten.
Wenn wir in unseren Commits den Trailer Changelog: <added/changed/removed> verwenden, parst die Änderungsprotokoll-API von GitLab diese und verwendet sie, um automatisch ein Änderungsprotokoll für uns zu erstellen!
Sehen wir uns das in Aktion an, indem wir Änderungen an einer echten Codebase vornehmen, eine Release durchführen und dann Versionshinweise und Änderungsprotokoll-Einträge generieren.
Beispielprojekt
Für diesen Blog verwende ich ein einfaches Python-Web-App-Repository. Nehmen wir an, dass Version 1.0.0 der Anwendung gerade veröffentlicht wurde und die aktuelle Version des Codes ist. Ich habe auch die Release 1.0.0 in GitLab erstellt, was ich manuell tun musste, da wir unsere automatisierte Release-Pipeline ja noch nicht erstellt haben:
Nehmen wir unsere Änderungen vor
Wir entwickeln rasend schnell und arbeiten daher schon daran, Version 2.0.0 unserer Anwendung heute zu veröffentlichen. Im Rahmen unserer Release 2.0.0 fügen wir eine neue Funktion zu unserer App hinzu: einen Chatbot! Wir werden auch die Quanten-Blockchain-Funktion entfernen, da wir diese nur für die erste Finanzierungsrunde benötigt haben. Außerdem fügen wir einen automatisierten Release-Job zu unserer CI/CD-Pipeline für unsere Release 2.0.0 hinzu.
Zuerst entfernen wir die nicht benötigten Funktionen. Ich habe einen Merge Request erstellt, der die notwendigen Änderungen enthält. Wir müssen sicherstellen, dass wir eine Commit-Nachricht haben, die den Trailer Changelog: removed enthält. Dazu gibt es mehrere Möglichkeiten: Wir können ihn unter anderem direkt in einen Commit einbauen oder einen interaktiven Rebase durchführen und über das CLI hinzufügen. Der einfachste Weg in unserem Fall ist meiner Meinung nach, bis zum Ende zu warten und dann die Schaltfläche Edit commit message in GitLab zu verwenden, um den Trailer folgendermaßen zum Merge-Commit hinzuzufügen:
Mit dieser Methode kannst du auch den Titel des Merge-Commits auf einen prägnanteren Titel ändern. Ich habe den Titel meines Merge-Commit auf „Nicht verwendete Funktionen entfernen“ geändert, da dies im Eintrag im Änderungsprotokoll angezeigt wird.
Als nächstes fügen wir einige neue Funktionen für die Version 2.0.0 hinzu. Hier müssen wir nur einen weiteren Merge Request öffnen, der unsere neuen Funktionen enthält, und dann den Merge-Commit bearbeiten, sodass er den Trailer Changelog: added enthält, und dann den Commit-Titel auf einen prägnanteren Titel ändern:
Jetzt sind wir eigentlich bereit, 2.0.0 zu veröffentlichen. Aber dieses Mal möchten wir unsere Release nicht manuell erstellen. Deshalb fügen wir vor der Release einige Jobs zur Datei .gitlab-ci.yml hinzu, die die Release automatisch für uns durchführen und die entsprechenden Versionshinweise und Einträge ins Änderungsprotokoll erstellen, wenn wir unseren Code mit einer neuen Version wie z. B. 2.0.0 taggen.
Hinweis: Wenn du Änderungsprotokoll-Trailer erzwingen möchtest, solltest du überlegen, etwas wie Gefahr bei der Durchführung automatischer Überprüfungen für MR-Konventionen (nur in englischer Sprache verfügbar) zu verwenden.
Erstellen einer automatisierten Release-Pipeline
Damit unsere Pipeline funktioniert, müssen wir ein Projektzugriffstoken erstellen, mit dem wir die GitLab-API aufrufen können, damit sie die Einträge im Änderungsprotokoll erstellt. Erstelle ein Projektzugriffstoken im API-Bereich (nur in englischer Sprache verfügbar) und [speichere das Token dann als CI/CD-Variable (nur in englischer Sprache verfügbar)]((https://docs.gitlab.com/ee/ci/variables/#define-a-cicd-variable-in-the-ui) mit dem Namen CI_API_TOKEN. Wir verweisen auf diese Variable, um uns bei der API zu authentifizieren.
Nun fügen wir zwei neue Jobs zu unserer Datei gitlab-ci.yml hinzu:
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_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG:$CI_COMMIT_SHA"
In der oben angeführten Konfiguration verwendet prepare_job die Befehle curl und jq, um den Endpunkt der Änderungsprotokoll-API von GitLab aufzurufen und übergibt dies dann an unser release_job, um die Release zu erstellen. Genauer gesagt sieht das so aus:
- Wir verwenden das Projektzugriffstoken, dass wir zuvor erstellt haben, um die Änderungsprotokoll-API von GitLab aufzurufen, die dann die Versionshinweise erstellt. Wir speichern dies als Artefakt.
- Wir verwenden die Variable
$CI_COMMIT_TAGals Version. Dazu müssen wir eine semantische Versionierung für unsere Tags verwenden (beispielsweise so etwas wie2.0.0). Du wirst auch bemerkt haben, dass ich den Release-Job mit dem Abschnittruleseingeschränkt habe, der auf ein semantisches Versions-Tag überprüft.- Damit die Änderungsprotokoll-API von GitLab funktioniert, ist eine semantische Versionierung erforderlich. Sie verwendet dieses Format, um die neueste Release zu finden und sie mit unserer aktuellen Release zu vergleichen.
- Wir verwenden das offizielle Image
release-clivon GitLab. „release-cli“ ist erforderlich, um das Schlüsselwortreleasein einem Job zu verwenden. - Wir verwenden das Schlüsselwort
release, um eine Release in GitLab zu erstellen. Dies ist ein spezielles Job-Schlüsselwort, das für die Erstellung einer Release und das Ausfüllen der erforderlichen Felder reserviert ist. - Wir können eine Datei als Argument an die
descriptionder Release übergeben. In unserem Fall ist es die Datei, die wir inprepare_joberstellt haben und die als Artefakt an diesen Job übergeben wurde. - Wir haben auch unser Container-Image, das früher in der Pipeline erstellt wurde, als Release-Asset hinzugefügt. Du kannst alle Assets aus deinem Build-Prozess anhängen, die du möchtest, z. B. Binärdateien oder Dokumentationen, indem du eine URL zu dem Ort angibst, an den du sie zuvor in der Pipeline hochgeladen hast.
Durchführen einer automatisierten Release
Mit dieser Konfiguration müssen wir nur ein Tag in unser Repository übertragen, das unserem Versionsschema entspricht, um eine Release durchzuführen. Du kannst einfach ein Tag mit dem CLI pushen. Für dieses Beispiel wird die GitLab-UI verwendet, um ein Tag im main-Branch zu erstellen. Erstelle ein Tag, indem du in der Seitenleiste „Code“ -> „Tags“ -> „Neues Tag“ auswählst:
Nach der Erstellung werden unsere Pipelines ausgeführt. Die Änderungsprotokoll-API von GitLab generiert automatisch Versionshinweise für uns als Markdown, der alle Änderungen zwischen dieser Release und der vorherigen Release enthält. Hier ist der Markdown, der in unserem Beispiel generiert wurde:
## 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))
Wie du sehen kannst, hat GitLab die Einträge für unsere Versionshinweise automatisch mit unseren Git-Commit-Trailern extrahiert. Außerdem werden hilfreiche Links zum Merge Request bereitgestellt, damit die Leser(innen) weitere Details und Diskussionen zu den Änderungen sehen können.
Und jetzt folgt unsere letzte Release:
Erstellen des Änderungsprotokolls
Als nächstes möchten wir unser Änderungsprotokoll aktualisieren (das im Grunde ein gesammelter Verlauf aller deiner Versionshinweise ist). Du kannst dazu eine POST-Anfrage an den Änderungsprotokoll-API-Endpunkt senden, den wir zuvor verwendet haben.
Du kannst dies auch als Teil deiner Release-Pipeline tun, wenn du möchtest. Dazu kannst du beispielswiese den folgenden Code in den Abschnitt script deines Vorbereitungsjobs einfügen:
'curl -H "PRIVATE-TOKEN: $CI_API_TOKEN" -X POST "$CI_API_V4_URL/projects/$CI_PROJECT_ID/repository/changelog?version=$CI_COMMIT_TAG"
Beachte dabei, dass dies das Repository ändert. Es wird ein Commit erstellt, um die neuesten Notizen zu einer Datei CHANGELOG.md hinzuzufügen:
Und das war’s auch schon! Indem wir den umfassenden Verlauf, den uns git bietet, mit praktischen Commit-Trailern nutzen, können wir die leistungsstarke API und die CI/CD-Pipelines von GitLab optimal einsetzen, um unsere Release-Prozesse zu automatisieren und Versionshinweise für uns zu erstellen.
Wenn du das Projekt erkunden möchtest, das wir für diesen Artikel verwendet haben, findest du es unter diesem Link.