Deployment nach GitHub Pages

Die Alternative für Kundenprojekte ohne PHP-Formulare. Der Workflow ist .github/workflows/deploy-pages.yml.

Voraussetzungen

deployment: {
  target: 'github-pages',
},
forms: {
  provider: 'none',        // oder 'joomla'
  captcha: 'none',
},

standalone-php ist mit diesem Ziel ausgeschlossen — GitHub Pages führt kein PHP aus, und die Konfigurationsprüfung lehnt die Kombination ab. Der Joomla-Provider funktioniert, weil sein Backend woanders läuft.

Eine deployment.apache-Sektion ist ebenfalls ausgeschlossen: Sie beschreibt eine Datei, die niemand liest.

Nur mit eigener Domain

site.url darf keinen Unterpfad enthalten. GitHub Project Pages liegen unter https://<org>.github.io/<repository>/ — und die internen Links dieses Starters sind absolute Pfade ab der Wurzel, die nirgends um ein Basisverzeichnis ergänzt werden. Eine Website unter einem Unterpfad würde bauen und mit lauter toten Links ausgeliefert.

Die Konfigurationsprüfung lehnt einen Pfad deshalb ab:

site.url: darf keinen Unterpfad enthalten — der Starter liefert nur im Wurzelverzeichnis aus

Möglich sind damit:

• eine eigene Domain (https://www.kunde.de) — der Regelfall
• eine User- oder Organization-Page (https://kunde.github.io)

Die Domain wird aus site.url in eine CNAME-Datei geschrieben. Bei Veröffentlichung aus einem Actions-Workflow wertet GitHub keine Datei aus dem Repository aus, deshalb entsteht sie im Artefakt. Damit gibt es keine zweite Stelle, an der die Domain eines Projekts steht.

Begründung in ADR 0014.

Einrichten

1. Settings → Pages → Source: „GitHub Actions"
2. Custom domain eintragen und den DNS-Eintrag setzen
3. Enforce HTTPS aktivieren, sobald das Zertifikat ausgestellt ist
4. Bei captcha: 'turnstile': Variable PUBLIC_TURNSTILE_SITE_KEY setzen

Es gibt keinen SSH-Schlüssel und keine Host-Variablen — die Übertragung läuft über das Pages-Artefakt.

Was fehlt im Vergleich zu Apache

GitHub Pages liefert keine eigenen Header aus. Damit entfällt alles, was bei mittwald-static aus der .htaccess kommt:

Was	Auf GitHub Pages
Content Security Policy	nicht vorhanden
X-Content-Type-Options	nicht vorhanden
Referrer-Policy	nicht vorhanden
Permissions-Policy	nicht vorhanden
HSTS	von GitHub gesetzt, wenn „Enforce HTTPS" aktiv ist
HTTPS-Weiterleitung	von GitHub, wenn „Enforce HTTPS" aktiv ist
Kanonische Domain	von GitHub für die eingetragene Custom Domain
Cache-Header	von GitHub gesetzt, nicht beeinflussbar
Kompression	von GitHub
Eigene 404-Seite	funktioniert — 404.html wird ausgeliefert
Projektweiterleitungen	nicht möglich

Keine Header, keine Ersatzlösung

Die Richtlinie über ein <meta http-equiv> auszuliefern wäre naheliegend und deckt die wichtigsten Direktiven nicht ab: frame-ancestors und report-uri sind im Meta-Element unwirksam. Der Starter erzeugt deshalb gar keine — statt einer, die die halbe Zusage einlöst (ADR 0013).

Für ein Projekt mit Formularen, Tracking oder Weiterleitungen ist mittwald-static das richtige Ziel.

Das Performance-Budget läuft trotzdem: Eine zu schwere Seite wird auf GitHub Pages nicht leichter.

Kein Konflikt mit der Starter-Dokumentation

Ein Repository hat genau eine Pages-Site. Im kanonischen Starter-Repository ist das die Dokumentation, veröffentlicht aus docs.yml. Beide Workflows prüfen deshalb github.repository und schließen sich gegenseitig aus:

Workflow	Läuft
docs.yml	nur im kanonischen Starter-Repository
deploy-pages.yml	nie im kanonischen Starter-Repository
deploy.yml	nie im kanonischen Starter-Repository

Ein Kundenprojekt löscht nach dem Initialisieren docs.yml und den Deployment-Workflow, den es nicht braucht. Bleibt einer liegen, bricht er mit einer Meldung ab, die auf deployment.target verweist, statt zu raten.