ADR 02: GitHub as the content store

Repos are the database. Branches are drafts.

Status: adopted (2026-07-14)

Context

Content needs storage, versioning, drafts, and publishing without adding a database or a paid service.

Decision

Each site’s GitHub repo is its content store. The console reads and writes through the GitHub API. AI page edits stage on preview/<timestamp> branches; Vercel builds public preview deployments per branch; publishing merges to main; discarding deletes the branch. Instant rollback uses Vercel’s promote API against any previous production deployment.

Consequences

• Full history and rollback for free. Every change is a commit.
• Preview links are shareable because deployment protection is disabled on content projects.
• Multi-file operations must use the git trees API for atomic single commits (see commitFiles in the console) or Vercel deploys once per file.
• GitHub API rate limits become the scaling ceiling somewhere past 50 highly active sites. Acceptable.
• Preview deep links append text fragments (#:~=…) pointing at added text so reviewers land on the change.