LaTeX-Dokumente mit GitLab CI rendern

Die Grundidee ist wie folgt: Lokal auf dem eigenen Rechner bearbeitet man das LaTeX-Skript, das zum Beispiel in einer Datei namens essay.tex abgespeichert ist. Möchte man das Skript rendern lassen, lädt man es auf einen Server hoch. Etwa eine halbe Minute später kann man sich dann das fertige PDF im Browser herunterladen. Möglich ist dies dank Git, Docker, GitLab und vor allem dank GitLab CI. Wie man sieht, ist Erfahrung mit Git hilfreich, ich werde aber im folgenden Artikel alles ausführlich erklären.

Wer sich mit Git und GitLab schon bestens auskennt und nur Interesse an der Konfiguration von GitLab CI hat, kann direkt nach ganz unten zur .gitlab-ci.yaml springen.

Git ist eine Software, die im Bereich der Software-Entwicklung der de facto Standard ist, um die vielen verschiedenen Dateien eines Projekts zu verwalten und die Zusammenarbeit mit anderen Entwickler:innen zu vereinfachen. Git kümmert sich darum, dass keine Änderung an einer lokalen Datei verloren geht und lokale Änderungen mit denen anderer Entwickler:innen synchronisiert werden. Um mit der Benutzung zu beginnen, öffnet man die Kommandozeile/PowerShell (unter Windows mit Shift + Rechtsklick, „PowerShell-Fenster hier öffnen“) und erstellt anschließend entweder mit git init ein neues, sogenanntes „Repository“ oder klont ein schon bestehendes: git clone https://codeberg.org/NicoAlt/tuda_latex_template_grundpraktikum.git

Im letzteren Fall wurden nun alle Dateien meiner Vorlage für das Physikalische Grundpraktikum an der TU Darmstadt heruntergeladen und befinden sich im Ordner tuda_latex_template_grundpraktikum.

Screenshot von https://codeberg.org/NicoAlt/tuda_latex_template_grundpraktikum, das eine Liste aller Dateien zeigt

Mithilfe von Texteditoren können nun die Dateien essay.tex und bibliography.bib bearbeitet werden. Selbstverständlich können auch komplett eigene LaTeX-Dokumente in diesem Ordner erstellt und bearbeitet werden.

Bevor diese Änderungen zu einem Server hochgeladen werden können, muss beim ersten Mal ein sogenannter „remote“ konfiguriert werden. Hierzu wird im Rahmen dieses Artikels GitLab verwendet. GitLab ist eine Webanwendung, die es erlaubt, Git-Projekte zentral zu verwalten und die Zusammenarbeit mehrerer Personen an einem Projekt zu ermöglichen. Neben den „Issues“ und „Merge Requests“, die uns an dieser Stelle weniger interessieren, ist ein wichtiger Bestandteil die sogenannte „GitLab CI“. „CI“ steht dabei für „Continious Integration“. GitLab CI erlaubt es, bei jeder neuen Änderung vorher festgelegte Prozesse ablaufen zu lassen und so zum Beispiel LaTeX-Skripte in fertige PDFs zu verwandeln.

Studierende und Beschäftige deutscher Universitäten können in vielen Fällen im Rahmen des Deutschen Forschungsnetzes (DFN) die GitLab-Instanz der RWTH Aachen benutzen. Das Problem hierbei ist allerdings, dass die RWTH Aachen keine „GitLab Runner“ anbietet. Ohne diese ist GitLab CI de facto nutzlos. Ich habe deshalb auf meinem Server einen eigenen GitLab Runner installiert und im GitLab der Universität konfiguriert, aber wer dies nicht möchte, kann stattdessen die Flagschiff-Instanz GitLab.com benutzen.

Hat man einen Account auf einer GitLab-Instanz erstellt, kann man nach der Anmeldung mit einem Klick auf das + oben rechts ein neues Projekt erstellen.

Screenshot eines leeren GitLab-Projekts, das unter anderem die URL für den remote enthält

Dort befindet sich dann die URL, die wir benötigen, um das Projekt als remote in unserem lokalen Git-Repository hinzuzufügen. Wenn man zu Beginn das Git-Repository mit git init erstellt hat, kann man das Projekt auf GitLab nun mit git remote add origin https://git.rwth-aachen.de:nico.alt/my-latex-essay.git hinzufügen. Hat man ein bestehendes Projekt geklont, besteht schon ein remote namens origin und man muss diesen mit git remote set-url origin https://git.rwth-aachen.de:nico.alt/my-latex-essay.git umkonfigurieren. Ein anschließender erster git push bringt dann die lokalen Dateien auf die GitLab-Instanz.

Screenshot des GitLab-Projekts, nachdem die Dateien hochgeladen wurden

Der grüne Haken im grauen Kasten links neben der Commit-ID 2fc37cd4 bedeutet, dass GitLab CI erfolgreich das PDF gebaut hat und dieses nun von der Adresse https://git.rwth-aachen.de:nico.alt/my-latex-essay/-/jobs/artifacts/master/raw/essay.pdf?job=build heruntergeladen werden kann. Ein Klick auf den grünen Haken führt zu der Pipeline „build“, in der ein Protokoll (log) des Dokumenten-Baus zu finden ist.

Screenshot des GitLab CI Jobs, in dem das erste PDF gebaut wurde

Dass im gezeigten Beispiel alles so wunderbar geklappt hat, liegt an der Datei .gitlab-ci.yml. Diese enthält die Anweisungen für GitLab CI und muss bei neuen Projekten manuell hinzugefügt werden.

image: registry.gitlab.com/islandoftex/images/texlive:latest

build:
  script:
    - pdflatex essay.tex
    - biber essay
    - pdflatex essay.tex
  after_script:
    - cat essay.log
  artifacts:
    paths:
      - essay.pdf

Möchte man nun die eigenen Änderungen zu GitLab hochladen, müssen im lokalen Ordner drei Befehle ausgeführt werden. Zuerst wird Git mithilfe von git add . mitgeteilt, dass alle Änderungen im lokalen Ordner („.“) vorgemerkt werden sollen. Anschließend teilt man Git mithilfe von git commit mit, dass diese Änderungen gespeichert werden sollen. Man muss daraufhin eine kurze commit message eingeben, in der kurz beschrieben werden kann, was sich geändert hat. Anschließend werden die Änderungen mit git push zu GitLab hochgeladen. Andere Mitwirkende am Dokument können sich die neusten Änderungen mithilfe von git pull auf den eigenen Rechner holen, wodurch eine Zusammenarbeit möglich wird. Durch die Nutzung von Apps wie LabCoat (Link zu Google Play) ist es außerdem möglich, von Mobilgeräten aus am LaTeX-Dokument zu arbeiten und das PDF mit dem Browser herunterzuladen.

Zur Vereinfachung des Textes wurden einige kleinere Punkte ausgelassen. So muss zum Beispiel beim GitLab der RWTH Aachen entweder ein Passwort vergeben oder ein SSH-Schlüssel hochgeladen werden, bevor git push benutzt werden kann. Ebenso muss im lokalen Git der Name und die E-Mail-Adresse konfiguriert werden, wie im Screenshot des leeren GitLab-Projekts oben vermerkt ist.

Hinweis: Statt GitLab CI zu benutzen, kann man auch Docker auf dem eigenen Computer installieren und dann lokal LaTeX-Dokumente bauen. Wie das geht, habe ich im Blog-Post LaTeX-Dokumente lokal mit Docker bauen beschrieben.