ADR-014 — GitHub Actions CI + GitHub Pages as preview environment
Status · Accepted Date · 2026-04-28 Supersedes · ADR-005 (Docker Compose as sole deployment target) TA anchor · §stack
Context
Production deployment platform is not yet decided. In the interim, GitHub Actions provides CI and GitHub Pages provides a free preview environment accessible at https://chipi.github.io/orrery. Docker Compose remains valid for local development and self-hosted deployment.
Decision
GitHub Actions for all CI (build, typecheck, lint, test, doc-check, asset fetch). GitHub Pages as the preview/staging environment on every push to main. Docker Compose retained for local development. Production hosting TBD.
Rationale
GitHub provides everything needed for free on a public repo: Actions minutes, Pages hosting, Dependabot, CodeQL. No third-party CI service needed. GitHub Pages serves the built static files from the gh-pages branch — same output that will go to production, just served from GitHub's CDN.
Alternatives considered
- Cloudflare Pages — strong candidate for production; global edge CDN; free tier generous; deferred until production decision is made.
- Vercel — also strong; Next.js-native but supports SvelteKit; deferred.
- Netlify — valid; deferred.
Consequences
Positive: free; zero configuration beyond the Actions workflow; every push to main is instantly previewable at a real URL. Negative: GitHub Pages base path (/orrery/) requires base: '/orrery/' in vite.config.ts for GH Pages deploy — production deploy will not need this; manage via environment variable.
Implementation notes
Two workflows: ci.yml (on every push/PR: build, typecheck, lint, test) and preview.yml (on push to main: build + deploy to gh-pages branch). Base path conditional on GITHUB_PAGES=true env var.