GitHub-Adapter

Setzkasten speichert alle Inhalte als JSON-Dateien direkt in deinem GitHub-Repository. Kein eigener Server, keine Datenbank — Git ist das Backend.

Wie es funktioniert

Jede Inhaltsspeicherung im Admin-UI erzeugt einen echten Git-Commit. Die GitHub Contents API schreibt direkt in den konfigurierten Branch — ohne lokales Checkout, ohne CI-Schritt.

✏️

Editieren

Admin-UI speichert Formulardaten

📦

Commit

GitHub API erzeugt atomaren Commit

🚀

Deploy

Webhook triggert Neubuild der Site

Ordnerstruktur im Repository

Setzkasten legt alle Inhalte im konfigurierten contentPath (Standard: content/) ab:

Repository-Struktur

content/
├── _sections/          ← Section-Inhalte (hero.json, features.json …)
│   ├── hero.json
│   └── features.json
├── pages/              ← Seiten-Konfiguration (Reihenfolge, aktiv/inaktiv)
│   └── _index.json
└── blog/               ← Collections (ein JSON pro Eintrag)
    ├── mein-erster-post.json
    └── second-post.json

Sections vs. Collections

Typ	Ablage	Inhalt
Section	content/_sections/hero.json	Einmaliger Seitenbereich (1 JSON = 1 Section)
Collection	content/blog/mein-post.json	Beliebig viele Einträge (1 JSON = 1 Eintrag)
Page-Config	content/pages/_index.json	Reihenfolge und Aktivierungsstatus der Sections

Beispiel: Section-JSON

Jede Section ist eine flache JSON-Datei. Feldnamen entsprechen den Keys aus dem Schema:

content/_sections/hero.json

{
  "heading": "Alles im Überblick",
  "subheading": "Dein Einstieg in das Headless-CMS",
  "ctaText": "Loslegen",
  "ctaUrl": "/docs/installation"
}

GitHub OAuth App einrichten

Für den Admin-Login benötigst du eine GitHub OAuth App in deinem Account oder deiner Organisation:

GitHub Settings

# GitHub → Settings → Developer settings → OAuth Apps → New OAuth App
Application name: Setzkasten CMS (My Site)
Homepage URL: https://deine-seite.de
Authorization callback URL: https://deine-seite.de/api/setzkasten/auth/callback

Wichtig: Die Callback-URL muss exakt mit deiner Produktions-URL übereinstimmen. Für lokale Entwicklung eine separate OAuth-App mit http://localhost:4321 anlegen.

GitHub Token für Commits

Für Content-Commits braucht der Server-Prozess einen GitHub Personal Access Token (classic) mit repo-Scope. Als Env-Variable GITHUB_TOKEN setzen.

Hinweis: Den Token nie in die Versionskontrolle committen. Bei Vercel/Netlify/Cloudflare als Environment Variable (encrypted) eintragen.

← Architektur API-Referenz →