Plan: GitHub Pages Deployment via 2-Repos

[mjkatgithub]

Kontext

Aktuell laufen Tests/CI in diesem Code-Repo. Das GitHub-Pages-Deployment passiert manuell: npm run generate und danach Dateien händisch in ein zweites Repo der Org decentra-chat (Pages-Repo) kopieren.

Ziel: Das Ganze automatisieren (Actions im Code-Repo), ohne lokale .env-Configs zu committen, und später den Repo-Transfer in die Org vorbereiten.

---

Plan (vollständig)

---
name: GitHubPagesDeployment
overview: Automatisiere das Deployment der generierten Nuxt-Static-Site aus dem Code-Repo in ein separates Org-GitHub-Pages-Repo, ohne lokale .env-Configs zu committen, und bereite den Repo-Transfer in die Org sauber vor.
todos:
  - id: confirm-static-output-dir
    content: Output-Pfad von `npm run generate` final bestätigen (`.output/public` vs `dist`).
    status: pending
  - id: choose-auth-method
    content: Auth-Methode festlegen (fine-grained PAT vs Deploy Key) und benötigte Secrets definieren.
    status: pending
  - id: add-deploy-workflow
    content: "`deploy-pages.yml` Workflow im Code-Repo entwerfen: generate + checkout Pages-Repo + copy + commit/push."
    status: pending
  - id: docs-env-config
    content: "README/Issue-Doku: welche `NUXT_PUBLIC_*` Variablen beim Build gesetzt werden können/sollen."
    status: pending
  - id: org-transfer-checklist
    content: Checkliste für Repo-Transfer in die Org (Secrets, Projects, Pages, Branch protections).
    status: pending
isProject: false
---

## Zielbild (dein Setup)
- **Code-Repo** (mit CI/Tests, Issues/Project): baut `nuxt generate`.
- **Pages-Repo** in `decentra-chat` (ohne Actions): enthält nur die generierten statischen Dateien für GitHub Pages.
- **Konfiguration** (z.B. optionales Debug-Logging) kommt aus **Env-Variablen** im Build-Job, nicht aus committeten `.env`-Dateien.

## Entscheidung: Wo liegen die generierten Dateien?
- Prüfe einmalig, **welcher Ordner** nach `npm run generate` tatsächlich entsteht und veröffentlicht werden soll:
  - häufig: `.output/public/` (Nuxt 3/4 + Nitro static)
  - manchmal: `dist/`
- Lege diesen Pfad als Variable im Workflow fest, z.B. `STATIC_DIR=.output/public`.

## Workflow-Design (Code-Repo)
- **Neuer Workflow** `deploy-pages.yml` im Code-Repo:
  - Trigger: `push` auf `master` (oder `develop`→`master` Release), optional `workflow_dispatch`.
  - Steps:
    - Checkout Code-Repo
    - Setup Node 20, `npm ci`
    - Setze Build-Env (z.B. `NUXT_PUBLIC_SITE_URL`, optional Debug-Log Variablen)
    - `npm run generate`
    - Checkout Pages-Repo in Unterordner (z.B. `pages-repo/`)
    - Ersetze Inhalt im Pages-Repo durch `STATIC_DIR` (z.B. delete all außer `.git`, dann copy)
    - Commit & push **im Pages-Repo**

## Auth für Push ins Pages-Repo
- Wähle eine der sauberen Varianten:
  - **Fine-grained PAT** (empfohlen für Solo):
    - PAT als Secret im Code-Repo: `PAGES_REPO_TOKEN`
    - Zugriff: nur das Pages-Repo (Contents: Read/Write)
  - **Deploy Key** (alternativ):
    - SSH Deploy Key mit write access im Pages-Repo
    - Private Key als Secret im Code-Repo
- Hinweis: `GITHUB_TOKEN` reicht **meist nicht**, um in ein anderes Repo zu pushen.

## Custom Domain Vorbereitung
- Sobald ihr eine Domain habt:
  - Workflow schreibt (oder bewahrt) `CNAME` im Pages-Repo.
  - GitHub Pages Settings in der Org konfigurieren.

## Repo-Transfer in die Org (später)
- Vor dem Transfer:
  - Liste aller benötigten **Secrets/Variables** dokumentieren (Actions-Secrets werden i.d.R. nicht „mitgenommen“).
  - Prüfen, ob dein GitHub Project ein **User-Project** oder bereits ein **Org-Project** ist.
- Transfer:
  - Repo in Org verschieben.
  - Actions/Rules/Branch protections neu prüfen.
  - Secrets/Variables in der Org/Repo neu setzen.
  - PAT/Deploy-Key Rechte ggf. neu vergeben.

## Ergebnis-Artefakt: „detailliertes Issue“
- Erstelle ein Feature-Issue (unter eurem Epic/Phase), das enthält:
  - Goal
  - Scope (Workflow-Datei, Secrets, Copy-Strategie, CNAME)
  - Acceptance Criteria (Auto-Deploy funktioniert, kein manuelles Kopieren mehr)
  - Test-Checklist (Dry run via `workflow_dispatch`, Verify Pages URL)
  - Branch-Name (z.B. `feature/gh-pages-deploy`)