Wenn semantische Versionierung und Automatisierung zusammentreffen! 🤔

Die Verwaltung von Softwareversionen ist eine der grundlegenden Herausforderungen in der modernen Softwareentwicklung. Ohne ein durchdachtes Versionierungskonzept droht das gefürchtete „Dependency Hell“ – ein Zustand, in dem Abhängigkeiten zwischen Softwarekomponenten zu unvorhersehbaren Fehlern und Inkompatibilitäten führen. Dieser Beitrag zeigt, wie wir die semantische Versionierung in unseren GitLab CI/CD-Pipelines automatisiert haben, mit dem Ziel die Protokollierung, Nachverfolgbarkeit und Konsistenz über alle Deployment-Artefakte hinweg zu gewährleisten – von OCI-Images bis hin zu Programm-Bibliotheken.

In der Welt des Software-Managements existiert ein gefürchteter Ort namens „Dependency Hell“. Je größer ein System wächst und je mehr Pakete integriert werden, desto wahrscheinlicher ist es, dass man sich eines Tages an diesem Abgrund der Verzweiflung wiederfindet.

Ein anschauliches Beispiel liefert André Monteiro in seinem Blog: Eine NestJS-Anwendung, die wochenlang problemlos lief, stürzte plötzlich nach einem neuen Build ab – nur weil eine transitive Abhängigkeit (das ws-Paket) die Unterstützung für Node 6 in Version 7 eingestellt hatte, ohne dass die übergeordneten Pakete ihre Versionsnummern entsprechend angepasst hatten.

Solche Szenarien verdeutlichen, warum semantische Versionierung nicht nur eine Best Practice, sondern eine Notwendigkeit für professionelle Softwareentwicklung ist.

Semantische Versionierung (Semantic Versioning) ist ein Konzept von Tom Preston-Werner, Mitgründer von GitHub und Erfinder von Gravatar, für die Versionsnummernvergabe von Programmen und Softwarekomponenten. Die vollständige Spezifikation ist unter semver.org verfügbar. Eine Versionsnummer besteht aus drei Teilen: MAJOR.MINOR.PATCH (z. B. 1.10.24). Zusätzlich verwenden wir optional einen Build‑Indikator als Pre‑Release‑Suffix -bN (z. B. 1.10.24-b1). Hinweis: Die SemVer‑Spezifikation notiert Build‑Metadaten mit einem + (z. B. 1.10.24+0041). Wir weichen hier bewusst leicht ab und verwenden -bN; die Bedeutung (interner Buildzähler) bleibt gleich.

1.2.3-b4
│ │ │ └── Build (bN) – interner Buildzähler
│ │ └── Patch
│ └─── Minor
└──── Major

Versionstyp	Beschreibung	Beispiel
PATCH	Fehlerkorrekturen, abwärtskompatibel	1.0.0 → 1.0.1
MINOR	Neue Funktionen, abwärtskompatibel	1.0.0 → 1.1.0
MAJOR	Inkompatible API-Änderungen, Breaking Changes	1.0.0 → 2.0.0
BUILD	Entwicklungsfortschritt, interne Builds	1.0.0 → 1.0.0-b1

Hauptversionsnummer (Major Release): Eine Änderung der MAJOR-Versionszahl bedeutet, dass es Änderungen an der Art und Weise gibt, wie das Programm, Skript oder die Softwarekomponente zu verwenden ist – zum Beispiel Änderungen der Eingabeparameter oder Breaking Changes in der API.

Nebenversionsnummer (Minor Release): Eine Änderung der MINOR-Versionszahl bedeutet eine Erweiterung der Funktionen ohne Beeinträchtigung der Kompatibilität zu früheren Versionen. Es gibt neue Funktionen, aber die alten Funktionen funktionieren wie bisher.

Revisionsnummer (Patch Release): Eine Änderung der PATCH-Versionszahl bedeutet eine Fehlerkorrektur, die voll kompatibel zu früheren Versionen ist. Hier hat sich nur intern etwas geändert.

Buildnummer: Die Buildnummer kennzeichnet den Fortschritt der Entwicklungsarbeit in Einzelschritten und wird beispielsweise bei jedem Kompilieren des Codes um eins erhöht.

Die manuelle Vergabe von Versionsnummern ist fehleranfällig und zeitaufwändig. Entwickler vergessen häufig, die Version zu aktualisieren, oder wählen inkonsistente Versionsnummern. Durch die Automatisierung der Versionsnummern-Generierung zum Build-Zeitpunkt minimieren bzw. verhindern wir die falsche und fehlende Verwendung der Versionsnummer.

Jedes Deployment-Artefakt muss eine semantische Versionsnummer verwenden. Nur so kann eine Traceability und Nachverfolgbarkeit gewährleistet werden. Wir verwenden hierzu Tags im Commit-Statement, aus denen die semantische Versionsnummer abgeleitet wird.

• Konsistenz: Alle Artefakte folgen demselben Versionierungsschema
• Nachverfolgbarkeit: Jede Version kann eindeutig einem Commit zugeordnet werden
• Fehlerreduktion: Keine manuellen Fehler bei der Versionsvergabe
• Zeitersparnis: Entwickler müssen sich nicht um Versionsnummern kümmern
• Rollback-Fähigkeit: Eindeutige Identifikation für Rollbacks

ür unsere Deployment-Artefakte nutzen wir Build-Pipelines unseres Sourcecode-Managementsystems GitLab. Die Versionsnummer wird während des Builds über Commit-Kommentare bestimmt und die Versionsnummern-Vergabe automatisch durchgeführt.

Keyword im Commit	Versionsänderung	Beispiel
major	MAJOR +1, MINOR=0, PATCH=0	1.0.0 → 2.0.0
feature	MINOR +1, PATCH=0	1.0.0 → 1.1.0
patch, bugfix, fix	PATCH +1	1.0.0 → 1.0.1
(kein Keyword)	BUILD +1	1.0.0 → 1.0.0-b1

Ein Commit mit der Nachricht feature: Neue Exportfunktion hinzugefügt führt automatisch zu einer Minor-Version-Erhöhung. Ein Commit mit bugfix: Fehler in der Datumsvalidierung behoben erhöht die Patch-Version.

Semantische Versionierung ist nicht auf einen Artefakt-Typ beschränkt. Wir setzen sie für verschiedene Deployment-Artefakte ein:

Für containerisierte Microservices (z. B. data-importer, data-receiver) durchläuft unsere CI/CD-Pipeline folgende Schritte:

1. Version Calculation Stage:
   Das version-manager.sh-Skript liest die aktuelle Version aus der release-notes.json, analysiert die Commit-Nachricht auf Keywords und berechnet die neue Versionsnummer.
2. Build Stage:  Das OCI-Image wird mit der neuen Versionsnummer gebaut und als v{VERSION}-{BRANCH} getaggt.
3. Publish Stage: Das OCI-Image wird in die GitLab Container Registry gepusht.
4. Update Stage:  Das update-main-ci.sh-Skript aktualisiert die Versionsvariablen in der .gitlab-ci.yml und die Release Notes werden automatisch ergänzt.
5. Commit Stage: Die Änderungen werden automatisch committet mit einer Nachricht wie chore: update data-importer version to v1.0.1.

Für Java-Bibliotheken, die als JAR-Dateien verteilt werden (z. B. invoice-transformer), ist die semantische Versionierung besonders wichtig. Diese Bibliotheken werden von anderen Projekten als Abhängigkeiten eingebunden – genau hier entsteht das „Dependency Hell“, wenn Versionen nicht korrekt gepflegt werden.

1. Maven-Abhängigkeitsauflösung: Maven verwendet Versionsnummern, um die richtige Version einer Bibliothek zu laden. Ohne eindeutige Versionen können Konflikte entstehen.
2. Reproduzierbare Builds: Mit einer festen Versionsnummer kann ein Build jederzeit reproduziert werden.
3. Kompatibilitätsprüfung: Entwickler können anhand der Versionsnummer erkennen, ob ein Update Breaking Changes enthält.
4. Package Registry Integration: GitLab Package Registry organisiert Pakete nach Versionen – ohne semantische Versionierung ist eine saubere Paketverwaltung unmöglich.

1. Version Calculation:  Identisch zu OCI-Images – das version-manager.sh-Skript berechnet die neue Version.
2. Build Package: Das update-pom-version.sh-Skript aktualisiert die Version in der pom.xml, dann wird mit mvn clean package das JAR gebaut.
3. Publish to Registry: Das JAR wird mit mvn deploy in die GitLab Package Registry hochgeladen:
4. Update Config: Die aktualisierte pom.xml, das JAR und die Abhängigkeiten werden ins Repository committet.

mvn deploy:deploy-file \
  -DgroupId=com.example.invoice \
  -DartifactId=invoice-transformer \
  -Dversion=${INVOICE_PACKAGE_VERSION} \
  -Dpackaging=jar \
  -Dfile=target/invoice-transformer.jar \
  -Durl=${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/maven

Beispiel einer versionierten pom.xml:

<groupId>com.example.invoice</groupId>
<artifactId>invoice-transformer</artifactId>
<version>1.2.0</version>  <!-- Automatisch aktualisiert -->
<packaging>jar</packaging>

Verwendung in anderen Projekten:

<dependency>
    <groupId>com.example.invoice</groupId>
    <artifactId>invoice-transformer</artifactId>
    <version>1.2.0</version>
</dependency>

Besonders wertvoll ist die automatische Dokumentation in der release-notes.json. Jeder Build erzeugt einen Eintrag mit Version, Build-Datum, Commit-Nachricht und optional Kompatibilitätsinformationen:

{
  "version": "v1.0.0",
  "buildAt": "2025-10-23",
  "releaseNotes": "Major first release\n- Logging to nfs-share\n- Version management",
  "compatibilityInfos": {
    "PostgreSQL": "v3.5.3-b1",
    "Kafka": "v3.6.1-b1",
    "Zookeeper": "v3.8.3-b1"
  }
}

Entwickler können Kompatibilitätsinformationen direkt im Commit-Kommentar angeben:

feature: Neue Datenbankanbindung Compatibility: - data-receiver: v1.2.0 or higher - PostgreSQL: v16.0 or higher

Diese Informationen werden automatisch geparst und in der JSON-Datei gespeichert.

In verteilten Systemen mit mehreren Microservices ist die Dokumentation von Kompatibilitäten kritisch. Ein typisches Szenario verdeutlicht dies:

Das Szenario: Ein verteiltes System besteht aus mehreren Komponenten, die über einen Message Broker miteinander kommunizieren:

Das Problem: Bei einem Deployment wurde eine neue Version des API-Service ausgerollt, die ein geändertes Nachrichtenformat für den Message Broker verwendete. Der Consumer war jedoch noch auf die alte Version konfiguriert und konnte die neuen Nachrichten nicht verarbeiten. Gleichzeitig war der Producer auf eine Version aktualisiert worden, die mit dem alten Consumer-Format inkompatibel war.

Die Folge:

• Nachrichten wurden nicht mehr korrekt verarbeitet
• Fehler traten erst zur Laufzeit auf – nicht beim Build
• Die Fehlersuche war zeitaufwändig, da unklar war, welche Versionen miteinander kompatibel sind

Die Lösung: Durch konsequente Dokumentation der Kompatibilitäten in den Release Notes kann vor einem Deployment geprüft werden, ob alle Komponenten zueinander passen. Hätte das Deployment-Team die Release Notes des neuen API-Service geprüft, wäre sofort ersichtlich gewesen, dass Consumer und Producer ebenfalls aktualisiert werden müssen:

{
  "version": "v2.0.0",
  "buildAt": "2025-10-28",
  "releaseNotes": "Major: Neues Nachrichtenformat für Message Broker",
  "compatibilityInfos": {
    "database": "v3.5.0 or higher",
    "message-broker": "v3.6.0 or higher",
    "api-service": "v2.0.0",
    "consumer": "v2.0.0 or higher",
    "producer": "v2.0.0 or higher",
    "data-importer": "v1.5.0 or higher"
  }
}

1. Immer dokumentieren
   Bei jeder Änderung, die andere Komponenten betrifft, Kompatibilität angeben
2. Mindestversionen angeben
   Nicht nur „kompatibel mit“, sondern „v1.2.0 or higher“
3. Breaking Changes markieren
   Bei MAJOR-Versionen explizit auf Inkompatibilitäten hinweisen
4. Infrastruktur einbeziehen
   Auch Message Broker, Datenbanken, Cache-Systeme etc. dokumentieren
5. Vor Deployment prüfen
   Release Notes aller zu deployenden Komponenten vergleichen

In Kubernetes-Deployments mit Helm werden die Image-Versionen in values.yaml definiert. Die Kompatibilitätsinformationen aus den Release Notes helfen dabei, konsistente Deployments zu gewährleisten:

# deployment/values.yaml
api-service:
  app:
    image: registry.example.com/myproject/api-service:v2.0.0
 
consumer:
  app:
    image: registry.example.com/myproject/consumer:v2.0.0
 
producer:
  app:
    image: registry.example.com/myproject/producer:v2.0.0
 
# Alle Versionen müssen laut Release Notes kompatibel sein!

1. Welche Version wird aktuell deployed?
2. Welche Versionen laufen bereits in der Zielumgebung?
3. Sind alle Versionen laut Release Notes kompatibel?

Tipp: Automatisierte Kompatibilitätsprüfungen können in die CI/CD-Pipeline integriert werden, um vor dem Deployment zu warnen, wenn inkompatible Versionen kombiniert werden sollen.

Um die Version eines Deployment-Artefaktes abzufragen, stellen wir eine dedizierte, standardisierte API bereit. Für Microservices in einer Cloud-nativen Architektur erfolgt die Abfrage über den Endpunkt /version:

{
  "version": "1.0.2",
  "build": "abc12345",
  "commit_hash": "a1b2c3d4e5f67890abcdef1234567890"
}

Anforderung	Beschreibung
Einheitlichkeit	Die Abfrage muss für jede Deployment-Artefakt-Kategorie identisch sein
Öffentlich zugänglich	Die Abfrage muss ohne Authentifizierung möglich sein
Konsistenz	Die Abfrage muss den gleichen Wert liefern wie in Logdateien
Lesbarkeit	Die Ausgabe muss natürlich lesbar sein (z. B. UTF‑8‑Text)

Wir integrieren die Versionsinformationen immer in der Log-Ausgabe des Deployment-Artefaktes. Nur so können die Logeinträge eindeutig der jeweiligen Softwareversion zugeordnet werden.

Bereich	Nutzen
Rollback-Strategien	Eindeutige Identifikation des letzten lauffähigen Softwarestandes für schnelle Rollbacks
Konsistenz	Standardisierter Ansatz erleichtert Verwaltung und Überwachung komplexer Architekturen
Automatisierung	Klare Struktur ermöglicht einfache Automatisierung der Versionsprüfung in CI/CD-Pipelines
Debugging	Schnelle Zuordnung von Logeinträgen zur exakten Softwareversion
Compliance	Nachweisbarkeit welche Version zu welchem Zeitpunkt im Einsatz war

Die automatisierte semantische Versionierung in GitLab CI/CD ist mehr als nur eine technische Spielerei – sie ist ein fundamentaler Baustein für professionelle Softwareentwicklung. Durch die konsequente Anwendung vermeiden wir das gefürchtete „Dependency Hell“, ermöglichen präzise Rollbacks und schaffen Transparenz über den gesamten Software-Lebenszyklus.

Die Investition in ein durchdachtes Versionierungskonzept zahlt sich mehrfach aus:

• Weniger Fehler durch inkonsistente Versionen
• Bessere Nachverfolgbarkeit bei Problemen
• Klare Kommunikation über Änderungen zwischen Teams und Stakeholdern
• Reproduzierbare Builds und Deployments
• Einfache Integration in Package Registries (Maven, npm, Docker)

Ob Docker-Images für Microservices oder JAR-Bibliotheken für Maven-Projekte – das Prinzip bleibt gleich: Jedes Artefakt erhält eine eindeutige, semantisch aussagekräftige Versionsnummer, die automatisch aus dem Commit-Kontext abgeleitet wird.

1. Die offizielle Spezifikation von Tom Preston-Werner – Semantic Versioning Specification (SemVer)
2. Blog des SemVer-Erfinders und GitHub-Mitgründers – Tom Preston-Werner’s Blog
3. Praxisbeispiel zu Dependency Hell – André Monteiro – Semantic Versioning and why it’s important
4. Allgemeine Informationen zur Versionierung – Wikipedia – Versionsnummer
5. Tutorial zur GitLab-Integration – Medium – Automatic releases in GitLab
6. Offizielle GitLab-Dokumentation – GitLab Documentation – Package Registry