Ziel dieses Tutorials

Das folgende Tutorial zeigt, wie ein GitLab-Projekt für das gemeinsame Schreiben eines Textes eingerichtet und GitLab im Sinne eines Content Management Systems (CMS) genutzt werden kann. Die Autor_innen erhalten immer ein fertiges PDF bzw. LibreOffice-Dokument, wenn sie in GitLab einen Text schreiben bzw. ändern.

Idee und Motivation

Tools und Plattformen für die gemeinsame Arbeit an Texten gibt es mittlerweile einige: GoogleDocs, Etherpads und Hackpads sind hierbei sicherlich die bekanntesten, Lösungen im Rahmen der bekannten Office-Suiten ergänzen das Spektrum.

Neben diesen vielen Möglichkeiten gehen wir an der TUHH noch einen anderen Weg beim kollaborativen Schreiben, indem wir GitLab im Sinne eines Content Management Systems (CMS) einsetzen. Motiviert ist dieser Ansatz dadurch, dass wir auch Menschen, die nicht programmieren, an partizipative und kollaborative Prozesse im Netz heranzuführen möchten, an deren Ende ein digitales Artefakt steht. Diese können in ausführbarer Software, in kompletten Webseiten oder auch nur in Textdokumenten bestehen. Mit dem kleinsten gemeinsamen Nenner, dem Schreiben, wollen wir alle an der gleichen Stelle abholen und den Grundstein für eine interdisziplinäre Zusammenarbeit legen.

Voraussetzungen

• ein Nutzeraccount in GitLab an der TUHH mit der Möglichkeit, eigene Projekte anzulegen
• Grundkenntnisse in Markdown

Los geht’s!

Anlegen eines neuen Projekts und der Beispieldateien¹

Zunächst legen wir in GitLab ein neues Projekt an. Dabei ist nichts Besonderes zu beachten. Nun erstellen wir drei neue Markdown-Dokumente mit Beispieltexten, einleitung.md, hauptteil.md und schluss.md. Das Tutorial funktioniert auch mit einer einzigen Datei, wir wollen aber schon an dieser Stelle die Zusammenarbeit mit mehreren vorbereiten. So könnten unterschiedliche Autor_innen für einzelne Teile bzw. Dateien in einem größeren Text- oder Softwareprojekt zuständig sein.

Die README.md wurde beim Anlegen des Projekts erstellt. Die Blindtexte stammen aus dem Blindtextgenerator. Wichtig: Die Dokumente sollten eine Leerzeile vor der ersten Überschrift enthalten, damit die Markdowndateien bei Zusammenfügen richtig erkannt werden.²

Artefakte erzeugen: PDF- und LibreOffice-Dokumente

Ziel des nächsten Schrittes ist es, aus dem “Quellcode”, also unseren Markdowntexten, ein PDF bzw. LibreOffice-Dokument zu erstellen. Dieser Vorgang steht stellvertretend für einen Prozess, der continuous integration genannt wird und sich mittlerweile in der Softwareentwicklung etabliert hat. Kurz gesagt bedeutet er, dass neue Beiträge zum Quellcode kontinuierlich in das Gesamtprodukt einfließen und nach kurzer Zeit immer ein verbessertes und funktionsfähiges Produkt zur Verfügung steht.

Was wir in den folgenden Schritten tun, ist demnach nicht nur für den beschränkten Rahmen dieses Tutorials relevant. Vielmehr handelt es sich um Wissen, durch das die Mitarbeit auch in komplexeren Projekten möglich ist. Also – weiter!

Die Zutaten

Wir brauchen für nun folgenden Schritte vier Zutaten:

• pandoc, ein kommandozeilenbasiertes Konvertierungstool, das aus unseren Markdowndateien die Zieldateien generiert
• Docker, eine schlanke Virtualisierungslösung, die uns Container mit pandoc zur Verfügung stellen soll. In diesen Containern werden online unsere Zieldateien generiert.
• einen GitLab Runner. Dabei handelt es sich um ein Programm, das wir beauftragen können, etwas ganz Bestimmtes für uns zu tun, wenn bestimmte Ereignisse eintreten. Es wird dafür sorgen, dass bei jeder Änderung einer Markdowndatei ein Dockercontainer gestartet wird, in dem mit pandoc die Zieldateien generiert werden.
• eine Datei .gitlab-ci.yml, in der die bisherigen Zutaten entsprechend konfiguriert werden.

Die Konfiguration der Pipeline

Um continuous integration für unser Beispiel zu konfigurieren, verwenden wir die folgende .gitlab-ci.yml-Datei. Sie ist im Hauptverzeichnis unseres Repos anzulegen.³ In der offiziellen Dokumentation ist sehr ausführlich beschrieben, was hier noch zu welchem Zweck eingestellt werden kann.

image: marcelhuberfoo/pandoc-gitit

build:
  script:
    - pandoc *.md -o bericht.pdf 
    - pandoc *.md -o bericht.odt
  artifacts:
    paths:
      - "*.pdf"
      - "*.odt"

In der ersten Zeile steht, welches Dockerimage wir verwenden wollen. Das angegebene funktioniert gut, baut allerdings noch nicht auf der aktuellen Version 2.0 von pandoc auf. Es liegt bei Dockerhub und kann auch gegen andere oder eigene Images ausgetauscht werden.

In den restlichen Zeilen ist angegeben, welches Kommando in dem Dockercontainer ausgeführt werden soll, der jedes Mal vom GitLab Runner gestartet wird, um unsere Dokumente zu bauen.

Dabei sorgen die Zeilen

- pandoc *.md -o bericht.pdf 
- pandoc *.md -o bericht.odt

dafür, dass aus allen Markdowndateien im Verzeichnis die finalen Dokumente gebaut werden. Die Reihenfolge, in der wir die sie aneinanderhängen, ergibt sich aus der Nummerierung im Dateinamen.⁴

Das angegebene Dockerimage enthält eine lauffähige Version von pandoc, sodass wir den Befehl pandoc mit entsprechenden Parametern hier geben können. Wir tun dies zweimal, um die beiden verschiedenen Dokumentformate zu erhalten.

In dem Block, der mit artifacts überschrieben ist, sagen wir, dass wir die Endprodukte der Pipeline, also das, was generiert wurde, behalten möchten. Der Dockercontainer schiebt dann diese Artefakte zurück in unsere GitLab-Projekt, wo wir sie herunterladen können.

Pipelines

Pipelines sind in GitLab definierte Abläufe, in denen verschiedene Stadien eines Bauvorgangs oder auch build process nacheinander und parallel abgearbeitet werden. Unsere Pipeline hier ist sehr einfach aufgebaut, sie hat genau eine Stufe (stage), die in der .gitlab-ci.yml mit build benannt ist.

Nachdem wir unsere .gitlab-ci.yml angelegt haben, versucht GitLab die Konfiguration darin abzuarbeiten. Das gelingt noch nicht gleich, wie wir unter CI/CD -> Pipelines sehen können.

Ein Klick auf das Label Pending führt zu einer nächsten Seite, die den Aufbau der Pipeline genauer darstellt. Hier taucht der Name unserer einzigen Stufe (stage) auf.

Ein weiterer Klick auf das Label build zeigt uns, woran es liegt:

Wir haben noch keinen Runner für unser Projekt zugewiesen, der für unsere Pipeline zuständig ist. Wenn wir dem Link in der Meldung, Runners Page, folgen, können wir dies nachholen.

Den GitLab Runner zuweisen

GitLab Runner sind dafür zuständig, Jobs für uns zu erledigen. Sie können auf unterschiedliche Weise konfiguriert werden, was in der offiziellen Dokumentation von GitLab ausführlich beschrieben wird.

Im GitLab der TUHH stehen momentan zwei Runner zur Verfügung, die von Nutzer_innen der Instanz verwendet werden können. Unter Settings -> CI/CD -> Runners können diese geteilten Runner mit einem Klick auf Enable shared Runners aktiviert werden.

Ein erneuter Blick auf die Übersicht der laufenden Pipelines über CI/CD -> Pipelines zeigt, dass nach einer Weile unsere Pipeline abgearbeitet wird.

Ein Klick auf die Label Passed und auf der folgenden Seite auf build zeigt, was stattgefunden hat:

Unser GitLab-Runner auf flint2 zieht sich das angegebene Dockerimage marcelhuberfoo/pandoc-gitit und startet darauf einen eigenen Container. In den Container, den man sich als schlanke virtuelle Maschine vorstellen kann, clont der Runner nun den Inhalt unseres Repositorys und damit auch die drei Markdowndateien.

Anschließend lässt er auf den Dateien des Repositorys die Befehle laufen, die wir in der .gitlab-ci.yml angegeben haben, um letztlich die generierten Artefakte aus dem Container wieder in GitLab hochzuladen. Der Container hat nun seinen Dienst erfüllt und wird gelöscht, die Pipeline ist erfolgreich durchgelaufen. Aber wo sind jetzt unsere Dateien?

Zugriff auf die Artefakte

Auf die generierten Artefakte kann an verschiedenen Stellen zugegriffen werden.

Artefakte, die zum Job gehören

Artefakte, die in einem speziellen Job erzeugt wurden, können rechts neben dem Job Log über die Button Keep, Download und Browse gefunden werden (s. Screenshot oben).

Artefakte der letzten erfolgreichen Pipeline

Auf der Homepage des Projekts können die Artefakte der letzten erfolgreichen Pipeline heruntergeladen werden.

Zusammenfassung und Ausblick

Wenn alles geklappt hat, sind wir nun in der Lage, mit mehreren Autor_innen an einem Textprojekt zu schreiben oder auch allein an einem größeren Projekt wie einer Qualifikationsarbeit oder einem Forschungsbericht.

Die Idee war, GitLab im Sinne eines CMS zu verwenden, um digitale Artefakte zu erzeugen. Der Content, den wir hier managen, sind die Markdowndateien, die Ausgabe erfolgt in einem PDF- bzw. LibreOffice-Dokument. In zukünftigen Tutorials werden wir uns ansehen, wie in dem gleichen Verfahren auch Webseiten gepflegt werden können. Der vorgestellte Ansatz ist übertragbar auf andere Szenarien und hat damit eine relativ große Reichweite. Mit anderen Worten: Es lohnt sich, die Lernkurve von GitLab zu erklimmen, weil es sich um sehr universelle Kenntnisse und Kompetenzen handelt.

Ausgehend von diesem Tutorial werden wir in Zukunft weitere Praktiken und Verfeinerungen betrachten. So ist es interessant zu sehen, wie das PDF-Dokument formatiert werden kann oder Bilder eingebunden werden können. Aber auch Workflows mit Fokus auf Kollaboration und Qualitätskontrolle sind zu betrachten.

Weiterführende Links und Literatur

---

1. In der aktuellen Version von GitLab wird nach dem Anlegen eines neuen Projekts auch eine sogenannte Auto DevOps-Pipeline angelegt. Da wir diese nicht verwenden wollen, können wir sie über Settings -> CI/CD -> Auto DevOps deaktivieren, indem wir Default to Auto DevOps pipeline abwählen. Anschließend löschen wir noch unter CI/CD -> Pipelines die steckengebliebene erste Pipeline mit Klick auf den roten Button rechts.
2. Der Grund dieser Vorsichtsmaßnahme ist, dass die meisten Editoren den letzen Umbruch eines Textdokuments löschen, um einen sauberen Abschluss zu haben. Damit ist aber die Raute (#) der folgenden Überschrift nicht mehr sauber vom vorhergehenden Text abgetrennt. Es kann auch \newpage vor der ersten Überschrift gesetzt werden, womit ein manueller Seitenumbruch erzeugt wird.
3. Da es sich bei der .gitlab-ci.yml um das YAML-Format handelt, ist streng auf die korrekte Einrückung der Zeilen zu achten!
4. Damit die README.md nicht auch in unser Dokument einfließt, benennen wir sie um in README.markdown. Dadurch wird sie immer noch als Markdowndatei von GitLab erkannt, aber wegen der anderen Dateiextension nicht mehr einbezogen.
   Das Umbenennen lässt sich erledigen, indem die README.md editiert wird und dann einen anderen Namen erhält.

Dieser Beitrag wurde verfasst von Axel Dürkop.