The image is published to GHCR as the release's version when a release dispatches docker.yml, and never as latest or per commit. Pushes and pull requests that touch it build it and try headless (with and without a token) and browser mode, without publishing. The image: node:24-slim pinned by digest (the major CI tests on), npm ci from the lockfile in its own layer, only src, site, scripts and the harness copied in (an allow-list .dockerignore), root-owned and run as node, /saves ready for --save-dir. The entrypoint runs the servers with node directly and, with no SOT_MCP_TOKEN, makes a token for the run and prints it (MCP_NO_TOKEN=1 to opt out); the docs publish ports to 127.0.0.1 and explain --allow-host. Labels, SBOM and provenance on push. Every GitHub Action in every workflow is pinned to a commit SHA with its version, and Dependabot keeps the actions, the image's base and the npm tools current. tests/docker.test.js guards all of it. The ADR and the github-pages skill say the image is a tool: GHCR only, never Pages.
3.5 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. - Tools are not hosting.
npm run dev, the MCP server and the container image that packages them (docker/, published to GHCR for releases) are tools. What someone serves with them is theirs; seriesoftub.es is the game, and nothing is ever deployed anywhere but GitHub Pages. - 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.