Verteilungssicht: Ein Push auf main, ein Artefakt, GitHub Pages liefert Apps und Doku aus

Die Apps laufen vollständig im Browser des Kindes. GitHub baut und liefert aus; es gibt keinen Rechner, den jemand betreiben muss. Ein Workflow baut die Site mit Eleventy und diese Doku mit docToolchain und legt beides in ein einziges Pages-Artefakt.

Infrastruktur Ebene 1: GitHub baut, Pages liefert, der Browser rechnet

verteilung
Element Zweck und Zuordnung

Repository

lernapps/lernapps.github.io, öffentlich, in der Organisation lernapps. Der Name <org>.github.io macht die Site zur Organisations-Site an der Wurzel https://lernapps.github.io/ (ADR-015).

pruefen.yml

Bei jedem Push und PR: npm ci, npm audit --audit-level=high, npm run lint (ESLint mit no-eval und no-unsanitized, T-003), npm run typecheck (tsc --checkJs für src/kern), npm test, npm run build (inklusive Build-Prüfungen). Berechtigung nur contents: read. Baut die Doku nicht; das übernimmt doku.yml.

doku.yml

In PRs, die src/docs, src/site, die docToolchain-Konfiguration oder die Ausgabeprüfung ändern (paths-Filter), und manuell, Job doku-bauen-und-pruefen: Java 17, Graphviz, scripts/dtc-v4.sh generateSite (Cache je gepinntem docToolchain-Commit), danach node lib/pruefe-ausgabe.js build/microsite/output --ausser lunrjsindex.js. Berechtigung nur contents: read. Fehler in AsciiDoc oder PlantUML zeigen sich so vor dem Merge (erledigt TD-22 und TD-23).

browser.yml

Bei jedem Push und PR, Job browser: npm ci, npm run build, Chromium installieren (Cache je Playwright-Version), npm run test:browser gegen das gebaute _site/ (Playwright + axe-core, e2e/). Berechtigung nur contents: read. Eigener Workflow parallel zum Pflicht-Check test-und-build, der dadurch unverändert und schnell bleibt; selbst ebenfalls Pflicht-Check browser (ADR-026).

abhaengigkeiten.yml

Bei jedem PR, Job abhaengigkeiten: actions/dependency-review-action v5.0.0, per Commit-SHA gepinnt, vergleicht die Abhängigkeiten mit der Basis des PRs. Neue Pakete dürfen nur Lizenzen der dev-Allowlist aus lib/pruefe-lizenzen.js tragen und keine Schwachstelle ab high (wie npm audit --audit-level=high). Kein PR-Kommentar, Berechtigung nur contents: read. Seit 25.09.2026 Pflicht-Check abhaengigkeiten (ADR-029).

ki-review.yml

Bei jedem eingereichten oder geänderten PR-Review, Job ki-review: liest die Reviews des PRs und prüft mit scripts/ki-review-pruefen.js, ob das neueste ## KI-Review den Kopf-Commit nennt (Stand:) und Ergebnis: freigegeben meldet. Ruft kein Sprachmodell auf; Berechtigungen contents: read, pull-requests: read (ADR-027).

pages.yml

Bei Push auf main und manuell: npm ci, npm test, npm run build; danach Java 17, Graphviz und scripts/dtc-v4.sh generateSite. docToolchain v4 ist unveröffentlicht; das Skript holt main-4.x am festen Commit 6de96fb7 und baut dessen lib/ (TD-9). actions/cache hält Checkout samt lib/ und die Gradle-Abhängigkeiten je gepinntem Commit vor. Der Schritt „Doku nach _site/docs legen“ kopiert build/microsite/output/ nach _site/docs/, löscht landingpage.gsp (TD-16) und lädt _site als ein Artefakt hoch. Berechtigungen pages: write, id-token: write.

GitHub Pages

Liefert https://lernapps.github.io/ und …/docs/ aus. Quelle „GitHub Actions“ (heute build_type: workflow, per gh api repos/lernapps/lernapps.github.io/pages geprüft am 23.09.2026). Jede Datei kommt mit Cache-Control: max-age=600; deshalb setzt der Build ?v=<Hash> (ADR-014).

Browser

Führt Kern und Fachmodule aus; speichert nur im localStorage. Braucht ES-Module und import(). Je App erlaubt manifest.webmanifest „Zum Startbildschirm hinzufügen“.

Stolperstein: Ein Repo <org>.github.io schaltet Pages im Branch-Modus ein

Wer ein Repository mit dem Namen <org>.github.io anlegt, bekommt GitHub Pages automatisch eingeschaltet, und zwar im Modus „Deploy from a branch“. Dann liefert Pages die Quellen aus main aus, nicht die Ausgabe von pages.yml: Die Seiten wären Nunjucks-Rohtext, und deploy-pages schlägt fehl. Die Quelle muss einmal auf „GitHub Actions“ umgestellt werden:

gh api -X PUT repos/lernapps/lernapps.github.io/pages -f build_type=workflow
gh api repos/lernapps/lernapps.github.io/pages --jq .build_type   # erwartet: workflow

Für ein Repository ohne Pages lautet der erste Aufruf gh api -X POST …/pages -f build_type=workflow (CLAUDE.md, „Build, test, deploy“).

Ein Deployment wechselt alle URLs auf einmal

GitHub Pages erlaubt dem Browser, jede Datei zehn Minuten lang ohne Rückfrage aus dem Cache zu nehmen, jede für sich. Der Build hängt deshalb an jede lokale Referenz ?v=<Hash über alle JS/CSS/JSON>; ändert sich eine ausgelieferte Datei, zeigen alle Seiten auf neue URLs, die kein Cache kennt. Nur die HTML-Seite selbst kann bis zu zehn Minuten alt sein (R-013).

Lokal: fünf Befehle genügen

npm ci                          # Eleventy 3.1.6 exakt nach package-lock.json
npm test                        # Unit-, Vertrags- und Build-Tests
npm run build                   # _site/, bricht bei Regelverstößen ab
npm run serve                   # Dev-Server
scripts/dtc-v4.sh generateSite  # Doku nach build/microsite/output/ (holt beim ersten Mal docToolchain v4)