- docs/adr/0001: GitHub Pages is the only host, not open for renegotiation - docs/adr/0002: source in many files, shipped as one page assembled at build - tests/pages.test.js: builds stay static files Pages can serve, all local references resolve, only release.yml deploys and only via the Pages actions - tests/build.test.js: partial naming and layout rules - new skills: github-pages, edit-the-game; add-strings, performance, release and write-tests updated for src/, sorted dictionaries and --base-ref - CLAUDE.md, ARCHITECTURE.md, CONTRIBUTING.md (incl. porting older branches), README.md and the PR template describe the new layout
3.2 KiB
ADR 0001: Series of Tubes is hosted on GitHub Pages, and only there
- Status: accepted, not open for renegotiation
- Date: 2026-10-27
- Decided by: Frederic Jung
Decision
The game is served by GitHub Pages, from the custom domain in site/CNAME
(https://seriesoftub.es). That is the only hosting. There is no second host, no fallback host and no
plan to move.
Every change has to keep working there. A change that only works with a server, a different host, a CDN in front, edge functions, rewrites or custom response headers is the wrong design for this project, however good it is otherwise. Change the design, not the host.
What GitHub Pages gives us, and what it does not
| We can rely on | We cannot have |
|---|---|
| Static files over HTTPS from one origin, with gzip | Any server code: no API routes, no SSR, no PHP, no edge or serverless functions |
The deploy in release.yml (actions/upload-pages-artifact + actions/deploy-pages) |
Custom HTTP headers (Cache-Control, CSP, COOP/COEP): use <meta> tags or do without |
404.html for unknown paths |
Redirect or rewrite rules (_redirects, .htaccess, vercel.json, netlify.toml) |
CNAME for the domain |
Per-file caching rules: Pages sets its own short cache lifetime for everything |
| A size limit of about 1 GB for the site and 100 MB per file | Secrets at runtime: everything in _site/ is public |
Anything that needs data at runtime fetches it from the same origin as a static file
(version.json), from the player's own browser (localStorage), or not at all.
Consequences
- The build is the place for work. Anything clever (assembling the page from
src/, stamping the version, baking release notes) happens inscripts/build.js, at build time, in GitHub Actions. The build may get slower; what it produces must stay plain static files. See ADR 0002. - Same origin for everything the game loads. The page, the dictionaries, icons and the service worker all come from seriesoftub.es. The only cross-origin requests are the web fonts and the privacy-friendly analytics counter (its script and its endpoint), and the game works without both. Don't add more: no CDN-hosted libraries, no third-party APIs the game depends on.
- The service worker is the cache policy. Since Pages decides HTTP caching,
site/sw.jsdecides what is cached for offline play, versioned by the release. - Deploys only come from releases.
release.ymlis the only workflow withpages: write. Pushes tomainnever deploy. - Tests guard it.
tests/pages.test.jschecks that a build is plain static files that GitHub Pages can serve as they are: no server or host configuration files, every local reference resolving inside_site/, nothing over the size limits,CNAMEand404.htmlin place, and the deploy going through the official Pages actions.
Proposals that are out of scope
Moving to Netlify, Vercel, Cloudflare Pages or a VPS; putting a CDN or proxy in front; adding a backend for accounts, leaderboards or cloud saves; server-side rendering. Features in that direction must be built from static files and the browser (for example, an exported save file instead of a cloud save), or not at all.