CI (GitHub Actions usw.)

CI (Continuous Integration) bedeutet, dass ein Server bei jedem Push automatisch Ihr PDF baut. Sie haben stets die aktuelle Ausgabe, ohne lokal kompilieren zu müssen, und „funktioniert auf meinem Rechner“-Probleme fallen früh auf. Für LaTeX ist GitHub Actions die übliche Wahl: Es checkt das Repository aus, kompiliert in einer TeX Live-Umgebung und speichert das erzeugte PDF als Artifact.

Warum in CI bauen

Bei jedem Push wird das Dokument automatisch in einer sauberen, reproduzierbaren TeX Live-Umgebung gebaut. Die Vorteile: Sie finden Fehler, die von Ihrer lokalen Einrichtung abhingen, früh; das Dokument ist nachweislich immer kompilierbar; Mitautorinnen, Mitautoren und Gutachter ohne TeX-Installation können trotzdem das aktuelle PDF erhalten; und bei Bedarf können Sie es als Release veröffentlichen. Den Build definieren Sie in einer Workflow-Datei (YAML) unter .github/workflows/.

Ein minimaler GitHub Actions-Workflow

Legen Sie das folgende YAML als .github/workflows/build.yml ab, und es funktioniert: actions/checkout holt den Quellcode, xu-cheng/latex-action kompiliert ihn, und actions/upload-artifact speichert das PDF. Die Hauptversionen von GitHub Actions ändern sich im Lauf der Zeit; dieses Beispiel nutzt die aktuellen Hauptlinien von 2026: checkout v6 und upload-artifact v7.

# .github/workflows/build.yml
name: Build LaTeX
on: [push]
permissions:
  contents: read
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: xu-cheng/latex-action@v4
        with:
          root_file: main.tex
      - uses: actions/upload-artifact@v7
        with:
          name: PDF
          path: main.pdf

xu-cheng/latex-action benötigt root_file und verwendet standardmäßig pdfLaTeX. Um die Engine zu wechseln, setzen Sie latexmk_use_xelatex: true oder latexmk_use_lualatex: true. Für Workflows wie upLaTeX + dvipdfmx, die genauere Schritte brauchen, committen Sie eine .latexmkrc und lassen die Action dieselbe Konfiguration wie Ihr lokaler Build lesen.

Dieses YAML ist die kleinste Form, um zu prüfen, ob das PDF erzeugt werden kann. Für eine Abschlussarbeit oder einen gemeinsamen Artikel sollte es sowohl bei push als auch bei pull_request laufen, damit ein defektes PDF vor dem Review auffällt. Action-Hauptversionen ändern sich; für eine langlebige Vorlage nehmen Sie entweder Dependency-Update-PRs an oder planen jährlich eine Prüfung gegen die offiziellen READMEs ein.

Die TeX Live-Umgebung — das texlive/texlive-Image

Der Build benötigt TeX Live, und latex-action bringt eines mit. Wenn Sie die Umgebung genauer steuern möchten (bestimmte Pakete, Japanisch usw.), können Sie direkt das Docker-Image texlive/texlive von Island of TeX verwenden. Da latest im Lauf der Zeit neu gebaut wird, pinnen Sie für reproduzierbare Abgaben einen datierten Tag oder einen TeX Live-Jahrestag und nutzen latest für tägliche Prüfungen. Geben Sie es als container: des Jobs an und führen Sie latexmk selbst aus.

jobs:
  build:
    runs-on: ubuntu-latest
    container: texlive/texlive:latest
    steps:
      - uses: actions/checkout@v6
      - run: latexmk -pdf main.tex
      - uses: actions/upload-artifact@v7
        with:
          name: PDF
          path: main.pdf

Wenn CI fehlschlägt, das Log lesen

Teilen Sie CI-Fehler zuerst in drei Gruppen: LaTeX-Fehler, fehlendes Paket oder falscher Artifact-Pfad. Zeigt das Log ! LaTeX Error oder Undefined control sequence, debuggen Sie das Dokument. Wenn File ... not found auf ein fehlendes TeX Live-Paket hinweist, passen Sie Image oder Installationsschritt an. Meldet upload-artifact, dass keine Dateien gefunden wurden, prüfen Sie path: gegen den tatsächlichen Ausgabenamen. Wenn es lokal funktioniert, aber nur in CI scheitert, vermuten Sie Schriften, Bilder oder erzeugte .bbl-Dateien, die nur auf Ihrem Rechner existieren.

PDF als Artifact — und als Release

• Das von actions/upload-artifact gespeicherte PDF ist auf der Workflow-Run-Seite herunterladbar (pro Lauf aufbewahrt).
• Für eine öffentliche Version können Sie das PDF an ein GitHub Release anhängen (z. B. ausgelöst durch das Pushen eines Tags).
• Für Japanisch bauen Sie im texlive/texlive-Container mit latexmk, konfiguriert für uplatex + dvipdfmx.
• Liefern Sie die Build-Konfiguration (.latexmkrc usw.) im Repository mit, damit lokal und in CI dieselben Schritte laufen.
• Für einen Abgabe-Workflow aktivieren Sie -halt-on-error und behalten Logs, damit Warnungen zurückverfolgt werden können.