Zum Hauptinhalt springen

Docs-Deployment

Die Docusaurus-Dokumentation wird als statische Website gebaut und über Cloudflare Pages veröffentlicht. Die Ziel-Domain ist:

https://docs.skintogo.de

Automatische Aktualisierung​

Der Workflow .github/workflows/deploy-cloudflare-pages.yml deployed automatisch bei jedem Push auf main im Docs-Repository.

Der Ablauf:

  • GitHub Actions checkt das Docs-Repository aus.
  • Node 20 wird eingerichtet.
  • Dependencies werden reproduzierbar mit npm ci installiert.
  • Docusaurus baut die statische Website mit npm run build.
  • Das erzeugte Verzeichnis build wird zu Cloudflare Pages veröffentlicht.
  • Nach erfolgreichem Deploy ist die aktualisierte Doku über docs.skintogo.de erreichbar.

Damit reicht für normale Doku-Änderungen:

git add .
git commit -m "docs: update documentation"
git push origin main

Der Push startet den Deploy automatisch.

Manueller Deploy​

Der gleiche Workflow kann manuell ausgelöst werden:

  1. Docs-Repository in GitHub öffnen.
  2. Actions auswählen.
  3. Deploy Docs to Cloudflare Pages öffnen.
  4. Run workflow anklicken.
  5. Branch main auswählen und starten.

Das ist nützlich, wenn ein früherer Deploy wiederholt werden soll, ohne einen neuen Commit zu erzeugen.

Pull-Request-Build​

Der Workflow .github/workflows/build.yml läuft bei Pull Requests und manuell per workflow_dispatch.

Er führt aus:

npm ci
npm run build

Dieser Workflow veröffentlicht nichts. Er prüft nur, ob die Docusaurus-Seite buildbar ist.

GitHub-Secrets​

Für den Cloudflare-Pages-Deploy müssen im Docs-Repository diese GitHub Actions Secrets existieren:

  • CLOUDFLARE_API_TOKEN
  • CLOUDFLARE_ACCOUNT_ID

Diese Werte dürfen nicht in Dokumentation, Logs oder Commits ausgegeben werden.

Cloudflare Pages​

Der Workflow veröffentlicht über cloudflare/pages-action@v1 direkt nach Cloudflare Pages. Das Cloudflare-Pages-Projekt heißt im Workflow:

skin-to-go-docs

Empfohlene Cloudflare-Pages-Einstellungen:

  • Production branch: main
  • Build output directory: build
  • Custom domain: docs.skintogo.de

Wenn Cloudflare Pages zusätzlich über die Cloudflare-Oberfläche mit GitHub verbunden wird, darf kein widersprüchlicher zweiter Build-Mechanismus entstehen. Entweder GitHub Actions veröffentlicht aktiv über cloudflare/pages-action, oder Cloudflare Pages baut selbst aus dem GitHub-Repo. Aktuell ist der GitHub-Actions-Weg vorbereitet.

Lokale Prüfung vor dem Push​

Falls lokal Node/npm verfügbar ist:

npm ci
npm run build

Falls lokal kein Node/npm verfügbar ist:

docker compose run --rm docs npm run build

Für die lokale Vorschau:

docker compose up --build

Danach im Browser:

http://localhost:3000

Was nicht automatisch passiert​

  • Änderungen im Hauptrepository skin_to_go deployen die Doku nicht automatisch.
  • Nur Commits im Docs-Repository skin_to_go_docs sind für den Docs-Deploy relevant.
  • App-Deployments und Docs-Deployments sind bewusst voneinander entkoppelt.
  • Secrets werden nicht aus der Doku erzeugt oder synchronisiert; sie müssen in GitHub und Cloudflare getrennt gepflegt werden.