Warum schlägt das Deployment einer Couscous-Seite auf GitHub Pages oft fehl?

Melden

Das Deployment einer Couscous-Seite (ein statischer Seitengenerator für PHP-Dokumentationen) auf GitHub Pages schlägt häufig aus spezifischen technischen Gründen fehl. Da GitHub Pages nativ auf Jekyll (Ruby-basiert) optimiert ist, Couscous aber PHP benötigt, entstehen Reibungspunkte.

Hier sind die häufigsten Gründe und wie man sie löst:

1. GitHub versucht, die Seite mit Jekyll zu bauen

GitHub Pages sucht standardmäßig nach einer Jekyll-Konfiguration. Da Couscous-Ordner oft mit Unterstrichen beginnen (z. B. _target), werden diese von Jekyll ignoriert oder falsch verarbeitet.

  • Problem: CSS-Dateien oder ganze Unterordner fehlen im Live-System.
  • Lösung: Erstelle eine leere Datei namens .nojekyll im Root-Verzeichnis deines Deployment-Branches (meist gh-pages). Dies weist GitHub an, den Inhalt einfach so auszuliefern, wie er ist.

2. Fehlende PHP-Umgebung in GitHub Actions

Couscous ist ein PHP-Tool. Wenn du versuchst, die Seite automatisch über GitHub Actions zu generieren, schlägt dies fehl, wenn PHP oder Composer nicht installiert sind.

  • Problem: Der Befehl couscous generate wird nicht gefunden.
  • Lösung: Nutze in deiner Workflow-Datei (.github/workflows/deploy.yml) die Action shivammathur/setup-php, um eine korrekte PHP-Umgebung bereitzustellen.

3. Falsche Pfade (Base URL Problem)

Wenn deine Seite nicht unter einer eigenen Domain (z. B. beispiel.de), sondern unter benutzername.github.io/projektname/ liegt, stimmen oft die Pfade zu CSS- und JS-Dateien nicht.

  • Problem: Die Seite wird als reiner Text ohne Design angezeigt.
  • Lösung: Überprüfe die couscous.yml. Du musst die baseUrl korrekt setzen, damit Couscous die Links relativ zum Unterverzeichnis generiert.

4. Authentifizierungsprobleme beim "Deploy"-Befehl

Couscous bietet einen integrierten Befehl couscous deploy. Dieser schlägt oft fehl, wenn er lokal ausgeführt wird, weil die SSH-Keys nicht korrekt für GitHub hinterlegt sind oder der Schreibzugriff auf den gh-pages-Branch verweigert wird.

  • Problem: Permission denied (publickey).
  • Lösung: Nutze stattdessen GitHub Actions für das Deployment. Das ist sicherer und automatisierter.

5. Veraltete Couscous-Version oder PHP-Inkompatibilität

Couscous wird nicht mehr so aktiv gepflegt wie früher. Neuere PHP-Versionen (8.x) können Warnungen oder Fehler in alten Couscous-Versionen auslösen.

  • Problem: Fehlermeldungen während der Generierung (Deprecated oder Fatal Error).
  • Lösung: Stelle sicher, dass du die aktuellste Version von Couscous verwendest oder fixiere die PHP-Version im Workflow auf 7.4, falls es Inkompatibilitäten gibt.

Zusammenfassung: Der "Best Practice" Workflow

Um Fehler zu vermeiden, sollte ein moderner Deployment-Workflow so aussehen:

  1. Lokal: Dokumentation in Markdown schreiben.
  2. GitHub Action:
    • Checke den Code aus.
    • Installiere PHP.
    • Installiere Couscous via Composer.
    • Führe couscous generate aus.
    • Erzeuge automatisch eine .nojekyll Datei.
    • Nutze eine Action wie JamesIves/github-pages-deploy-action, um den Inhalt des _target-Ordners in den gh-pages-Branch zu schieben.

Tipp: Wenn das Projekt neu ist, solltest du prüfen, ob Alternativen wie MkDocs (Python) oder Docusaurus (JS) besser geeignet sind, da diese heutzutage eine deutlich bessere Integration und Unterstützung für GitHub Pages bieten.

0