Mit Gitlab arbeiten

Zusammenfassung

Auf dieser Seite erfahren Sie, wie Sie in GitLab mit Branches, Commits und Merge Requests arbeiten und wie Sie Änderungen vor der Veröffentlichung sicher prüfen. Starten Sie dafür mit den Vorüberlegungen zur Veröffentlichungsstrategie: Vorüberlegungen

Branches, Commits und Merge Requests

Die Vorgehensweise und die verfügbaren, beziehungsweise zu erstellenden Branches unterscheiden sich abhängig von der gewählten Veröffentlichungsstrategie. Die beiden möglichen Strategien sind in den Vorüberlegungen zur Veröffentlichungsstrategie beschrieben.

Wichtiger Hinweis

Es muss klar sein, welche der beiden Strategien mit der betreffenden Dokumentation verfolgt werden soll. Dies hat Einfluss auf den Umgang mit Änderungen und die resultierende Arbeitsweise.

Nachfolgend betrachten wir zunächst die Vorgehensweise, wenn die Strategie "Kontinuierlichen Updates" zur Anwendung kommt. Das ist der Regelfall (im Anschluss erläutern wir die Unterschiede, falls die Strategie "Versionierung" angewendet werden soll).

Die Strategie "Kontinuierlichen Updates" ist einfacher in der praktischen Anwendung. Betrachten wir zunächst eine entsprechende Infografik:

Erklärtext zur Infografik

Die Infografik zeigt den typischen Ablauf ohne Versionierung:

• Oben verläuft der main-Branch als Hauptlinie.
• Darunter ist ein eigener Arbeits-Branch (z. B. für eine Textänderung) abgezweigt.
• Jeder Punkt auf einer Linie steht für einen Commit (eine gespeicherte Änderung).
• Der Merge Request „klammert“ den Arbeits-Branch: Er dient als Prüfstrecke, in der Änderungen besprochen und freigegeben werden, bevor sie in main zurückfließen.

Am Ende wird der Arbeits-Branch in main gemerged, sodass die Änderungen im Hauptzweig sichtbar werden.

WebIDE öffnen

Bevor Sie mit Branches und Commits arbeiten, müssen Sie die WebIDE starten. So gehts:

1. Öffnen Sie im GitLab-Projekt die Repository-Startseite und stellen Sie sicher, dass oben links der gewünschte Branch (meist main) ausgewählt ist
2. Öffnen Sie rechts oben das Dropdownmenü in der Schaltfläche Code und wählen Sie aus dem Menü den Befehl WebIDE oder drücken Sie die Taste ., um die WebIDE direkt zu öffnen.
3. Alternativ können Sie in einer Dateiansicht über das Dropdownmenü in der Schaltfläche Edit aus dem Menü den Befehl Open in WebIDE wählen oder die Taste . drücken, um die WebIDE direkt zu öffnen.

Sobald der Editor geladen ist, stehen Ihnen alle Funktionen im Browser zur Verfügung, ohne dass Sie lokal eine IDE installieren müssen.

Prozessschritte für Autor:innen in der WebIDE

Die Grafik zeigt den Ablauf bei der Arbeit an der Dokumentation. Da Sie in der WebIDE (dem Editor im Browser) arbeiten, müssen Sie keine Software installieren. Der Prozess sorgt dafür, dass Ihre Änderungen sicher sind, bevor sie für alle sichtbar werden.

Hier sind die drei Schritte, übersetzt in die Bedienung der WebIDE:

1. Branch erstellen (Ihren persönlichen Arbeitsraum öffnen)

Das Wichtigste zuerst: Arbeiten Sie nie direkt auf der Hauptseite (im main-Branch).
Erstellen Sie stattdessen eine Abzweigung, bevor Sie in der WebIDE etwas ändern.

• In der Grafik: Die Linie, die vom Hauptstrang nach unten abzweigt.
• In der WebIDE: Sie klicken in der unteren Statusleiste auf den aktiven Branch (im Screenshot der Branch main) oder im Branch-Menü (Strg Umschalt G) auf die drei Punkte oben, dann Branch → Create new branch.
• Der Prefix: Sie geben dem Branch einen Namen wie docs/neuer-artikel. Das Vorwort docs/ sorgt dafür, dass Ihr Branch im System automatisch in den Ordner für Dokumentationen sortiert wird. Das hilft dem Team, den Überblick zu behalten.

Weitere gebräuchliche Prefixes

Wenn Sie alle Branches betrachten, werden Ihnen vermutlich Branches mit anderen Prefixes auffallen. Hier eine Liste der gebräuchlichsten Prefixes:

• hotfix/...: Akute Produktionsfehler oder Build-Blocker, die sofort behoben und direkt nach main gemerged werden müssen.
• chore/...: Wartungsaufgaben ohne fachlichen Mehrwert (z. B. Abhängigkeiten aktualisieren oder Linting anpassen), damit solche Änderungen getrennt von Dokumentationsänderungen und Features bleiben.
• feature/...: Neue Funktionen, die strukturiert entwickelt und nach erfolgreicher Prüfung in main landen.
• test/...: Experimente oder Proof-of-Concepts, mit denen Workflows, Komponenten oder Konfigurationen gefahrlos ausprobiert werden können.

Was hier passiert: Ein Arbeitsbereich wird als Nebenzweig vom sogenannten main-Branch temporär abgespaltet, um diesen später - nach Durchführung aller Änderungen - in den Hauptzweig, dem main-Branch, wieder einzugliedern (mergen).
Um hier noch eine zusätzliche Qualitätssicherungsebene zu erhalten, wird ein Branch von einem GitLab Merge Request eingeklammert. Dieser bietet mehrere Funktionen, um ein Review der Änderungen nach dem Vier- oder Mehr-Augen-Prinzip durchzuführen, bevor die Änderungen im Branch des Nebenzweigs wieder in den Hauptzweig überführt werden.

Wichtig

Sobald Inhalte in den Hauptzweig (main-Branch) übernommen werden, sind sie direkt im öffentlichen Dokumentationsbereich sichtbar.
Um die Qualität zu gewährleisten, ist eine vorherige Prüfung – z. B. über die Vorschau (Preview) eines Merge Requests – zwingend erforderlich. GitLab bietet hierfür passende Werkzeuge, die Sie nutzen können.

Ebenfalls relevant für den Namen eines Branches ist die Issue ID. Diese sollte daher ebenfalls im Branchnamen untergebracht werden.

Warum die Issue-ID in den Branch-Namen gehört

In der Praxis erfolgen Änderungen selten „einfach so“, sondern basieren auf einem konkreten Arbeitsauftrag, der im System als Issue (oder Ticket) angelegt ist. Jedes dieser Issues hat eine eindeutige Nummer (die ID, z. B. #100).

Es ist „Best Practice“, diese ID direkt in den Namen Ihres Branches aufzunehmen. Beispiel: Statt nur docs/neuer-artikel nennen Sie den Branch docs/100-neuer-artikel.

Warum ist das sinnvoll?

1. Der „Rote Faden“ (Rückverfolgbarkeit): Sowohl Sie als auch Ihre Kolleginnen und Kollegen sehen am Branch-Namen sofort, zu welchem Arbeitsauftrag diese Textänderung gehört. Das verhindert Verwirrung, wenn parallel an mehreren Themen gearbeitet wird.

2. Automatische Verlinkung: GitLab ist schlau: Wenn die ID im Branch-Namen steht, erstellt das System automatisch einen Link zwischen Ihrer Arbeitskopie (Branch) und der Aufgabenbeschreibung (Issue). Man kann also später mit einem Klick vom Text zur Aufgabenstellung springen und umgekehrt.

2. Commit (Änderungen "fest" speichern)

Anders als beispielsweise in Word reicht in der WebIDE das einfache Speichern nicht aus, um Änderungen endgültig zu übernehmen. Dafür gibt es den 'Commit': Er speichert Ihre Änderungen dauerhaft in der Projektgeschichte – inklusive Autor und Zeitpunkt – und macht sie für andere sichtbar.

• In der Grafik: Jeder farbige Kreis auf einer Linie ist ein Commit.
• In der WebIDE: Nachdem Sie Ihren Text geschrieben/geändert haben (bei Bedarf auch in mehreren Dateien), klicken Sie links im Menü auf das "Source Control"-Symbol (meist ein kleiner blauer Kreis mit einer Zahl darin) oder drücken wieder Strg Umschalt G. In das Eingabefeld geben Sie eine kurze Nachricht ein (z. B. "Rechtschreibfehler korrigiert") und klicken auf Commit.
• Bedeutung: Damit sagen Sie dem System: "Ich bin mit diesem Abschnitt fertig, bitte nimm das in den Verlauf auf."

3. Einen Merge Request erstellen

Nach erfolgreichem Commit kann direkt über die Schaltfläche Create MR (erscheint unten rechts) ein neuer Merge Request angelegt werden, welcher im Anschluss noch bearbeitet werden kann.

Folgende Felder sollten im Merge Request geprüft und angepasst werden:

• Title – Bitte einen sprechenden Titel vergeben.
• Mark as draft - Es ist gute Praxis, einen neuen Merge Request zunächst als Entwurf zu kennzeichnen. Damit wird verhindert, dass jemand irrtümlich den Branch merged.
  Aktivieren Sie also die Checkbox Mark as draft.
• Description – Verfassen einer detaillierteren Beschreibung, damit andere einen Überblick über die inhaltlichen Änderungen im Merge Request erhalten können.
• Assignee – Haupt-Bearbeiter:in des Merge Requests (also Sie selbst)

Speichern Sie anschließend den Merge Request.

Über die Edit-Funktion lassen sich auch später noch Änderungen an den vorgenannten Angaben vornehmen. So tragen Sie den Reviewer (ein andere/-r Autor/-in oder ein/-e Redakteur/-in) beispielsweise erst dann in den Merge Request ein, wenn ein Review Ihres Merge Requests durchgeführt werden soll. Der eingetragene Reviewer wird daraufhin per E-Mail entsprechend informiert.

Alle anderen Einstellungen so belassen oder vornehmen, wie im Screenshot oben dargestellt und auf Save changes klicken.

Sie können anschließend zu Schritt 2. (Commit) zurückkehren und weitere Änderungen vornehmen.

4. Review durchführen

Bevor Änderungen in den Hauptzweig übernommen werden, sollten diese unbedingt durch eine zweite Person (oder mehr) gegengeprüft werden. Kriterien sind insbesondere:

• Sachliche Richtigkeit
• Rechtschreibung
• Satzbau (Lesefluss)
• Einheitliches Design verwendeter Grafiken (z. B. roter Kasten oder Ellipse?)

Die Änderungen können in der Change-View des Merge Requests eingesehen werden:

Für jede geänderte Datei wird ein Block angezeigt. Jede Änderung kann auch direkt dort kommentiert an der jeweiligen Zeile kommentiert werden. Ebenso können Änderungsvorschläge formuliert werden.

Die Änderungsvorschläge können angenommen oder auch verworfen werden.

Ist das Review erfolgreich abgeschlossen (ggf. nach mehreren Überarbeitungs-Schleifen, dann kann die reviewende Person dies auf der Übersichtsseite-Seite des Merge Requests (Overview)bestätigen. (→ Approve-Schaltfläche)).

5. Pipeline kontrollieren

Bevor Sie im nächsten Schritt die Vorschau (Preview) prüfen können, muss die Verarbeitung (Pipeline) erfolgreich durchgelaufen sein.

Keine Sorge

Sie können nichts kaputt machen: Wenn der Build fehlschlägt, wird die Website einfach nicht aktualisiert, bis der Fehler behoben ist.

Der Pipeline-Status zeigt Ihnen, ob Ihre Änderung erfolgreich gebaut wurde:

• Grünes Häkchen: Die Pipeline ist erfolgreich durchgelaufen, die Vorschau ist verfügbar (Schaltfläche View App)
• Rotes X: Die Pipeline ist fehlgeschlagen, es gibt eine Fehlermeldung im Job-Log
  Die vollständige Schritt-für-Schritt-Anleitung, was bei einer fehlgeschlagenen Pipeline zu tun ist, finden Sie auf der Seite GitLab-Fehler beheben. Diese Seite enthält auch den Job-Lotsen, der Fehlermeldungen eines Gitlab Jobs verständlich erklärt.

Den Pipeline-Status sehen Sie direkt im Merge Request (z. B. im Abschnitt Pipelines), zum Beispiel so:

6. Rendering-Ergebnis prüfen

Im Rahmen des Reviews ist auch oftmals sinnvoll, das Rendering zu prüfen.

Wie bereits erwähnt, generiert die GitLab CI Pipeline, die nach jedem Commit angestoßen wird, eine eigenständige Preview.

Nachdem Sie einen Merge Request erstellt oder einen neuen Commit hinzugefügt haben, dauert es in der Regel nur wenige Minuten, bis die Preview-Umgebung verfügbar ist. Sobald die Pipeline erfolgreich durchgelaufen ist, erscheint im Merge Request eine Schaltfläche View App (ggf. nach Neuladen der Seite)

Das Schema der Aufruf-Url dazu ist:
https://preview.docs.fitko.dev/<project-slug>/!<merge-request-id>

Die Preview-Ansicht ist auch über die Schaltfläche View App im Merge-Request erreichbar.

Preview-Link liefert einen 404-Fehler?

Preview-Umgebungen werden nach etwa einer Woche automatisch bereinigt (Job stop:preview).
Dadurch kann ein zuvor funktionierender Preview-Link im Merge Request auf 404 laufen.

Erkennbar ist das meist daran, dass der Job stop:preview bereits erfolgreich (grün) gelaufen ist.
Starten Sie in diesem Fall im betroffenen Merge Request die Pipeline erneut über Run pipeline, um die Preview wiederherzustellen.

7. Merge durchführen (Veröffentlichen / Zusammenführen)

Wenn Ihre Arbeit in der WebIDE erledigt ist, müssen Ihre Änderungen vom Neben-Gleis zurück auf das Haupt-Gleis (main), damit die Webseite aktualisiert wird.

Wenn der Merge Request noch im Draft-Modus ist, markieren Sie ihn zunächst als Ready.

• In der Grafik: Der Pfeil, der von unten zurück auf die dicke, obere Linie zeigt.
• In der WebIDE: Nach Ihrem letzten Commit erscheint meist ein Hinweis, einen "Merge Request" zu erstellen. Dies ist der "Antrag auf Zusammenführung".
• Der Vorgang: Wenn der Merge Request noch im Draft-Modus ist, dann ist der Merge Request zunächst als Ready zu markieren. Sie (oder eine:r der Redakteur:innen) klicken auf die Merge-Schaltfläche. Damit werden Ihre Texte aus dem Branch in den Hauptstrang kopiert. Die beiden blauen Kreise oben rechts in der Grafik symbolisiert diesen Moment: Ihre Änderungen sind nun "live".

Hinweis

Abhängig von den Rechte-Einstellungen kann es sein, dass Sie nicht schreibend auf den main-Branch zugreifen dürfen. In dem Fall lassen Sie den Merge durch eine:n Redakteur:innen durchgeführen.

Zusammenfassend für die WebIDE-Nutzung:

1. Branch: In der WebIDE einen neuen Arbeitsbereich mit dem Prefix docs/... anlegen, um nicht direkt auf main zu arbeiten
2. Commit: Änderungen fertigstellen, eine kurze Nachricht vergeben und in der Source-Control-Ansicht committen
3. Merge Request: Nach dem Commit einen Merge Request erstellen und Titel, Beschreibung sowie Zuständigkeiten pflegen
4. Review: Änderungen im Merge Request prüfen lassen und Feedback direkt in der Change-View adressieren
5. Pipeline kontrollieren: Den Build-Status der Pipeline prüfen (grünes Häkchen = erfolgreich, rotes X = fehlgeschlagen)
6. Preview prüfen: Die automatisch gebaute Docusaurus-Vorschau über View App oder die Preview-URL öffnen und das Rendering kontrollieren
7. Merge: Nach erfolgreichem Review den Merge Request bestätigen, damit der Branch wieder in main landet und veröffentlicht wird

Unterschiede "Versionierung"

Bei der Strategie "Versionierung" wird ein zusätzlicher Branch erzeugt, der üblicherweise die Bezeichnung develop trägt. Für diesen Branch wird ein Merge Request mit dem Zielbranch main erstellt.

Feature Branches werden nicht nach main gemerged, sondern in den develop Branch. So können Änderungen dort zunächst über einen gewissen Zeitraum gesammelt und in einer Preview-Umgebung begutachtet werden, bevor ein neues Release der Dokumentation durch Ausführen des Merge Requests für den develop-Branch veröffentlicht wird.

Erklärtext zur Infografik

Die Infografik zeigt den Ablauf mit Versionierung über einen zusätzlichen develop-Branch:

• main bleibt stabil und bildet den veröffentlichten Stand ab.
• Änderungen werden in Feature-Branches erarbeitet und anschließend in develop gemerged.
• In develop können mehrere Änderungen gesammelt und gemeinsam in einer Preview-Umgebung geprüft werden.
• Wenn ein Release ansteht, wird ein Merge Request von develop nach main erstellt und gemerged, damit die geprüften Änderungen veröffentlicht werden.

Versionierung mittels Docusaurus

Alternativ bietet sich die Versionierung in Docusaurus an. Hierfür sind allerdings eine lokale Git-Installation auf Ihrem Computer und ein Terminal erforderlich.
Ausführliche Informationen zur Docusaurus-Versionierung (öffnet in neuem Tab).