GitLab-CI-Monorepos: Do's und Don'ts für Pipelines

GitLab-Monorepo-CI – Do's and Don'ts

Dieser Beitrag zeigt, wie ihr Monorepo-Pipelines mit GitLab CI effizient verwaltet. Dabei nutzen wir moderne bedingte Logik, um schlanke und robuste Konfigurationen zu erstellen.

Mit GitLab 16.4 wurden neue Regeln eingeführt, die die Verwaltung von Monorepo-Pipelines mit GitLab CI erleichtern. Das ist wichtig für Leser, die möglicherweise ältere Versionen einsetzen.

Nachdem ich diese Pipelines mehrfach erstellt und wieder zum Scheitern gebracht habe, weiß ich genau, was funktioniert – und, noch wichtiger, was nicht funktioniert.

GitLab-Monorepo-Pipeline erklärt

Für diesen Blogbeitrag habe ich in meinem öffentlichen GitLab-Account eine technische Demo vorbereitet: Atihinen/monorepo-demo. Auf sie werde ich im weiteren Verlauf immer wieder Bezug nehmen.

Eine der zentralen Herausforderungen bei frühen Ansätzen für Monorepos war die Komplexität von CI/CD. Früher musstet ihr jede einzelne Sub-Pipeline- oder Job-Konfiguration bedingungslos einbinden und anschließend mühsam in jedem einzelnen Job Regeln definieren, die festlegen, ob er ausgeführt werden sollte. Das führte zu umfangreichen, schwer wartbaren Dateien und unübersichtlichen Pipeline-Auswertungen.

Dank Updates in GitLab, durch die das Keyword changes direkt in bedingten include-Anweisungen ausgewertet werden kann, können wir nun eine schlanke, robuste Pipeline auf oberster Ebene schreiben, die von Anfang an nur die benötigten Sub-Pipelines einbindet.

In meiner monorepo-demo habe ich eine Haupt-Pipeline konfiguriert, die zwei parallel entwickelte, unterschiedliche CLI-Tools verwaltet: eines in Go (cligo) und eines in Python (clipy) sowie einen Dokumentationsordner.

So orchestriert die Pipeline auf oberster Ebene diese Subprojekte bedingt:

Sehen wir uns nun meine Erkenntnisse aus den vergangenen zwei Jahren an.

Do: Definiert eure .gitlab-ci.yml präzise

Wenn ihr in GitLab CI die Root-Pipeline für ein Monorepo erstellt, solltet ihr die benötigten Stages sorgfältig definieren und planen. Stellt außerdem sicher, dass die Pipeline auf Root-Ebene Jobs enthält, falls die Sub-Pipelines keine Jobs für diese Stages überschreiben oder erstellen. Andernfalls kann es zu Fehlern zur Laufzeit kommen. Der „Platzhalter“-Job in der Haupt-YAML-Datei könnte zwar einfach etwas ausgeben, aber ich empfehle stattdessen, etwas auszuführen, das bereits einen Mehrwert für die Entwicklungsarbeit bietet.

In meinem Demo-Repository habe ich die folgenden Stages definiert (https://gitlab.com/Atihinen/monorepo-demo/-/blob/main/.gitlab-ci.yml?ref_type=heads#L2):

•  static_analysis

• build

In der Haupt-Pipeline habe ich die folgenden Jobs definiert:

Statt also alle Jobs einfach „something amazing“ ausgeben zu lassen, habe ich bereits auf der Hauptebene Standard-Linter hinzugefügt, da diese auch bei jedem Commit schnell ausgeführt werden können. Für die Build-Stage konnte ich leider keinen gemeinsamen Nenner definieren, da sie stark produktspezifisch ist.

Don't: Erwartet keine Anpassungen von Sub-Pipelines

Im vorherigen Kapitel habe ich euch gebeten, euch wirklich Gedanken darüber zu machen, welche Stages in der Pipeline enthalten sein sollen. Der Grund: GitLab unterstützt keine neuen Stages in Sub-Pipelines. Schaut euch diesen Commit an (https://gitlab.com/Atihinen/monorepo-demo/-/commit/e838b935e9e9ee6577e1ef9404339bca05418acc):

Dies führt in GitLab CI zu einem Fehler (https://gitlab.com/Atihinen/monorepo-demo/-/pipelines/1645391400):

deploy-go job: Die gewählte Stage deploy existiert nicht; verfügbare Stages sind .pre, static-analysis, build, .post
 

Do: Verwendet „needs“ statt neuer Stages

Neue Stages solltet ihr nur einführen, wenn sie tatsächlich von jeder Sub-Pipeline genutzt werden. Denn um auf der sicheren Seite zu sein, muss die oberste Ebene dann einen weiteren Job implementieren.

Im Beispiel aus dem vorherigen Kapitel würde die GoLang-Sub-Pipeline eine neue Stage „deploy“ für ein Deployment benötigen, das die Python-Pipeline nicht ausführt. Das lässt sich mit dem GitLab-Keyword needs lösen (https://docs.gitlab.com/ci/yaml/#needs). Damit können wir beispielsweise einen neuen Job in der Build-Stage definieren, der Deploy-Job wird jedoch erst ausgeführt, nachdem etwa der Job build-go abgeschlossen ist.

Nicht: Davon ausgehen, dass * ein Wildcard-Zeichen ist

Zunächst dachte ich, dass path/to/some/src/* ausreichen würde (https://gitlab.com/Atihinen/monorepo-demo/-/blob/main/.gitlab-ci.yml?ref_type=heads#L38):

GitLab interpretiert das Wildcard-Zeichen * nur auf der obersten Ebene des angegebenen Pfads. Unterverzeichnisse werden nicht rekursiv durchsucht.

Wie das in der Praxis funktioniert, könnt ihr hier prüfen (https://gitlab.com/Atihinen/monorepo-demo/-/pipelines/1643388739)

Dadurch wurde der erwartete mdlint-Job nicht ausgelöst (https://gitlab.com/Atihinen/monorepo-demo/-/pipelines/1643389164).

Tun: */** statt * verwenden

Im vorherigen Kapitel habe ich erklärt, warum path/to/something/in/repo/* keine gute Idee ist. Verwendet stattdessen path/to/something/in/repo/*/**, um jede Änderung unter diesem Pfad zu erfassen.

Beispiel:

Damit wird jede Dateiänderung im Verzeichnis cligo/ erfasst.

Fazit

Die neuen rules mit dem Schlüsselwort changes in GitLab CI sind ein leistungsstarkes Tool für Monorepos, bringen aber einige Fallstricke mit sich, die ihr kennen solltet. Hoffentlich helfen euch diese Beispiele dabei, nicht in dieselben Fallen zu tappen und zu viel Zeit mit der Fehlersuche zu verbringen, warum es nicht wie erwartet funktioniert.