feat: switch Keystatic from Cloud to GitHub mode

[rathermercurial]

Goal

Switch Keystatic storage from Cloud mode to GitHub mode, replacing Keystatic Cloud auth with
a self-managed GitHub App. The admin UI stays dev-only (NODE_ENV !== "production") — deploying
it to Netlify is tracked separately in #12.

Why

• No dependency on Keystatic Cloud (free tier limited to 3 users)
• GitHub mode uses a GitHub App (not OAuth App) — fine-grained permissions, per-repo access
• Unlimited users: anyone with GitHub write access to BreadchainCoop/bread-docs can edit
• Keystatic Cloud project bread/bread-docs can be decommissioned afterward

Config change

keystatic.config.tsx — two lines:

-  storage: { kind: 'cloud' },
+  storage: { kind: 'github', repo: 'BreadchainCoop/bread-docs' },

-  cloud: { project: 'bread/bread-docs' },

Collections, fields, Markdoc, and Breaditor branding stay the same.

Setup steps

1. Update config

Change keystatic.config.tsx as shown above.

2. Launch dev and trigger app creation

npm run dev

Visit http://localhost:4321/keystatic → click "Login with GitHub".

The first login triggers an interactive GitHub App creation wizard. Keystatic walks you through:

• Name the app (suggested: "Bread Docs CMS")
• Optionally fill in the deployed URL (leave blank for now — added in feat: deploy Keystatic admin UI to Netlify (SSR adapter + GitHub App redirect) #12)
• GitHub creates the app under your account/org

3. Grant repo access

After creation, GitHub prompts you to install the app. Grant it access to BreadchainCoop/bread-docs.
Permissions needed: Read & write (Contents + Metadata).

4. Env vars auto-generated

Keystatic writes these to .env (already in .gitignore ✅):

# Keystatic GitHub App credentials
KEYSTATIC_GITHUB_CLIENT_ID=...
KEYSTATIC_GITHUB_CLIENT_SECRET=...
KEYSTATIC_SECRET=...
PUBLIC_KEYSTATIC_GITHUB_APP_SLUG=...

Astro note: The env var prefix is PUBLIC_ (not Next.js's NEXT_PUBLIC_). Keystatic's Astro
integration reads from import.meta.env.PUBLIC_KEYSTATIC_GITHUB_APP_SLUG.

5. Verify

• Close browser, reopen /keystatic — login button uses GitHub, not Keystatic Cloud
• Log in successfully with your GitHub account
• Create a test entry, save — verify commit appears on GitHub
• Edit an existing page, save — verify commit appears on GitHub
• Branch dropdown visible in admin UI (confirms GitHub mode active)

6. Confirm admin UI stays dev-only

The astro.config.mjs guard ...(process.env.NODE_ENV !== 'production' ? [keystatic()] : []) still applies.
Running npm run build should NOT include Keystatic routes. Verify:

npm run build   # should succeed, no Keystatic API in output

Access model comparison

	Cloud (before)	GitHub (after)
Auth provider	Keystatic Cloud	Your GitHub App → user's GitHub
Who can edit	Keystatic Cloud team members	Anyone with repo write access
GitHub account required	No	Yes
User limit	3 free	Unlimited
Admin UI location	Dev only	Dev only (Netlify deploy: #12)

Cleanup (after verification)

• Remove Keystatic Cloud project bread/bread-docs from keystatic.cloud (optional, can keep as backup)
• Update AGENTS.md Keystatic section to reflect GitHub mode

Reference

• Keystatic GitHub mode docs
• GitHub App settings (BreadchainCoop org)
• GitHub App settings (personal)
• Redirect URI config (needed for feat: deploy Keystatic admin UI to Netlify (SSR adapter + GitHub App redirect) #12, not this issue)

Follow-up

• feat: deploy Keystatic admin UI to Netlify (SSR adapter + GitHub App redirect) #12 — Deploy Keystatic admin UI to Netlify (SSR adapter, env vars, redirect URI)