The scan job now runs both suites with coverage before scanning: pytest --cov (pyproject.toml: scripts/ without its tests, relative paths, coverage.xml) and `npm run test:coverage` (vite.config.ts: v8, lcov with projectRoot "..", so paths start web/). sonar-project.properties names both reports and drops sonar.coverage.exclusions. requirements-test.txt gains pytest-cov 7.1.0 and coverage 7.16.2 with every file's hash (uv pip compile --universal --generate-hashes --python-version 3.15; the existing pins are unchanged). web gains @vitest/coverage-v8 5.0.5, matching vitest; none of its packages has an install script. Coverage stays off for a plain `npm test`. The token check is its own job, so the scan steps no longer each repeat the condition; the workflow grants nothing at the top and the scan job contents: read. `npm run build:admin` replaces the bare `svelte-kit sync`: it syncs too, and writes the admin bundle the Worker's tests load. Locally: 576 vitest tests at 58.35% of lines, 299 pytest tests at 57.7%. Against main's new-code lines (SonarCloud's isNew), the reports cover 92 of 114 coverable lines, 80.7%: the 80% gate is borderline. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
15 KiB
Deployment
The site is a Cloudflare Worker serving a Vite build. Pushing to main is what
deploys — there is deliberately no deploy workflow in .github/workflows/.
How it fits together
push to main
└─> Cloudflare Workers Builds (root directory: web)
npm ci → npm run build → wrangler deploy
│ └─> Worker "free-steam-games-list"
│ ├─ static assets from web/dist
│ ├─ /api/data/* → proxies GitHub raw
│ ├─ /img/* → proxies Valve's CDN
│ ├─ /api/human-check → Turnstile siteverify (web only)
│ ├─ /admin → Access-gated admin SPA (embedded)
│ └─ /api/ingest/* → Access service token
├─ vite build → web/dist (the public site)
└─ vite build -c admin/… → web/worker/generated/admin-bundle.ts
The build runs on Node 26. The Worker's dashboard sets the build variable
NODE_VERSION=26 (Settings → Build → Variables and secrets); Cloudflare's
image would otherwise use its default, Node 24. web/.node-version says the
same, and CI and web/shared/toolchain.test.ts follow that file, but
Cloudflare does not document which directory it reads it from or which of the
two wins, so keep the variable and change both together. The first lines of a
build log show the Node actually used.
web/wrangler.jsonc is the only deployment config. Several fields in it are
load-bearing and easy to break:
namemust stayfree-steam-games-list. That is the Worker holding thefree-steam-games.wincustom domain. Deploying under any other name creates a second, domainless Worker and leaves the live site on the old build, with a completely green build log.assets.directorymust be./dist, not.. Pointing it at the source directory serves an unbuiltindex.htmlthat references/src/main.tsx— a blank page — and publishes the whole source tree. This happened.triggers.cronsdrives the reconciler. Remove it and approvals never leave theapprovedstate: nothing else promotes a row tocommitted, and nothing else ages out an approval the pipeline silently dropped. The queue keeps working and the failure is invisible until someone opens /admin.vars.ACCESS_AUD_ADMIN/vars.ACCESS_AUD_INGESTare per-route allowlists. Every Access application has its own AUD; add one without listing it here and every request through it is refused withaccess: aud mismatch. They are scoped by route on purpose — see docs/ADMIN.md.- The admin SPA is part of the Worker script, not of
dist/.npm run buildrunsbuild:adminafter the site build, which writes the gitignoredworker/generated/admin-bundle.tsthatworker/index.tsimports. Awrangler deploywithout that step fails to bundle, and that is the intended failure: the alternative, serving the admin fromdist/, would hand its code to anyone, to the service worker's precache and to the packaged apps.scripts/verify-dist.mjsfails the CI build if any admin code reachesdist/. The bundle adds about 0.5 MB to the Worker upload.
Data does not redeploy the site
The catalogue is proxied at /api/data/*, not built into dist/. A pipeline
commit to data/** therefore changes the site's content without any rebuild.
Keep it that way. If the data ever moves into the build output, the Worker's
build watch paths must include data/** — otherwise the site silently serves
a frozen dataset with no error anywhere, and a health check that reads the repo
rather than production will report green while it happens.
The one exception: prerendered game pages
Every /games/<appid> page is prerendered on the web build from data/ as it
stood at build time, so a crawler - which never accepts the terms and never
loads the catalogue - gets real content. Only the slow-changing fields are
baked in (name, description, artwork, studios, genre, platforms, tags); player
counts and reviews always come from /api/data/* in the browser.
That snapshot is therefore as fresh as the last deploy, and it should stay that way:
- The Workers Builds watch paths must exclude
data/**(dashboard → Worker → Settings → Build → Build watch paths; the configuration is under "Which commits deploy" below). Every bot data commit that deploys - several a day - rebuilds and re-uploads all ~5,700 files (measured on 2026-10-02: a 4-file data commit re-uploaded 5,681 assets, becausekit.version.nameis a timestamp) and gives every open tab a "Reload" prompt. - A game added after the last deploy has no file. The host answers with the
SPA fallback and
lib/fallback-route.tsrenders it client-side, so it works; it simply is not indexable until the next deploy. - A game removed since the last deploy keeps its file until then. Once the live
catalogue loads, the page shows "Game not found" with
noindex. F2P_SKIP_GAME_PRERENDER=1 npm run buildskips them for quick local builds. The Tauri builds never prerender them.
Which commits deploy (build watch paths)
Since 2026-10-02 a commit that touches only documentation does not deploy -
but data commits still did: 3f9e8cff ("Refresh store data
[2026-10-02]", four files under data/) deployed a new Worker version
(712b4ab8) at 16:54Z. The configuration below stops both. Skipping
everything outside web/ is right, with ONE trap: the web build reads the
legal documents. web/build/legal-versions.ts
hashes them for the consent gate and web/src/lib/server/markdown.ts
renders them at /legal/*:
LICENSE, LICENSE-DATA, docs/DISCLAIMER.md, docs/ToS.md,
docs/EULA.md, docs/PRIVACY_POLICY.md, docs/ACKNOWLEDGEMENTs.md,
docs/Contact.md
A commit that changes only those - the ToS edit Phase B needs, for one - would
not reach the site, and the consent gate would keep showing the old text and
hash until the next code deploy. Either keep those files triggering a build,
or redeploy by hand after merging such a change. Excludes are applied BEFORE
includes, so an exclude like docs/* swallows them whatever the include list
says. A configuration that does both jobs:
- Include:
web/*,LICENSE,LICENSE-DATA,docs/DISCLAIMER.md,docs/ToS.md,docs/EULA.md,docs/PRIVACY_POLICY.md,docs/ACKNOWLEDGEMENTs.md,docs/Contact.md - Exclude:
web/src-tauri/*,web/README.md
Everything not included - data/**, scripts/**, the other docs,
CHANGELOG.md, CLAUDE.md, README.md - then never deploys. Check it once
by merging a commit that touches only docs/plan/ (no build) and one that
touches only docs/ToS.md (a build), and by the next bot data commit: its
check runs on GitHub must have no Workers Builds: free-steam-games-list.
A check that IS there names a Version ID - that commit deployed.
Verifying a deploy
curl -sI https://free-steam-games.win/ | head -3
curl -s https://free-steam-games.win/ | grep -o '<html lang="[a-z]*"'
curl -so /dev/null -w '%{http_code}\n' https://free-steam-games.win/api/data/data/index.json
curl -so /dev/null -w '%{http_code} %{size_download}b\n' https://free-steam-games.win/img/t/570/header.jpg
curl -so /dev/null -w '%{http_code}\n' https://free-steam-games.win/admin # expect 302 to Access
curl -so /dev/null -w '%{http_code}\n' https://free-steam-games.win/api/ingest/ping # expect 302 to Access
The image should come back around 3–4 KB: the Worker prefers Steam's small capsule asset over the full header.
For the AVIF path, copy a game page's hero URL (/img/d/<appid>/…?t=…, the
?t= matters - it is part of the R2 key) and request it with
-H "Accept: image/avif": once the cron has minted it the answer is
image/avif with X-Img-Final: 1; before that it is the JPEG with
Cache-Control: public, max-age=86400 and no X-Img-Final.
The website itself loads that art from the bucket's custom domain instead
(docs/SECURITY_SETUP.md section 5): in a game page's Network panel the hero
is image/avif from https://media.free-steam-games.win/img/v2/460q80/…,
with cf-cache-status: HIT on a reload. A /img/d/… request right after it
means the media load failed and the fallback ran - expected for a game the
cron has not reached yet, a fault for one it has.
A stale service worker will show you the old app after a deploy. The site is a PWA, so a browser that visited before the deploy serves its cached shell until the service worker updates. If you are checking whether a deploy landed, use a fresh profile or a hard reload — otherwise you will diagnose a deployment problem that does not exist.
Local development
cd web
npm ci
npm run dev # Vite + HMR; /api/* and /img/* proxy to the live Worker
npx wrangler dev # the real Worker against web/dist — required for worker/ changes
npm run dev cannot exercise worker/ source. It proxies those paths to
production so the app has real data and images; changes under web/worker/
need wrangler dev.
Stop wrangler dev before running npm ci. On Windows the install deletes
node_modules and fails partway if a dev server holds files open.
Checks
.github/workflows/web-ci.yml runs on pull requests and on pushes to main
touching web/**, .github/workflows/** or sonar-project.properties:
npm ci --ignore-scripts, the typechecks (app, Worker and tests, on
TypeScript 7; the admin's svelte-check on TypeScript 6), npm test (which
includes the toolchain-pin and data-write-group checks over the workflows),
the build, scripts/verify-dist.mjs --web over the
prerendered HTML, npm run cf:check (wrangler deploy --dry-run), and
knip. python-tests.yml runs the pipeline's pytest suite on changes under
scripts/ and the requirements files, installing them exactly as the data jobs
do (--require-hashes --only-binary :all:).
It uses a plain npm ci, never npm ci || npm install. That fallback is what
hid a lockfile conflict which broke installs for a month. --ignore-scripts
keeps every dependency's install script from running with the job's token;
none of the three packages that have one needs it (the comment in
web-ci.yml says why), and no workflow runs npx, which can fetch a package
the lockfile never named.
CodeQL (codeql.yml) and SonarCloud (sonarcloud.yml) both look at pull
requests and main. Each posts a check on the pull request (CodeQL,
SonarCloud Code Analysis) about the issues the change brings in; the full list
for main lives in the repository's Security tab and on the SonarCloud
dashboard. sonar-project.properties at the root names the project and decides
what SonarCloud reads as code, what as tests, and what not at all (the dataset,
generated Android resources, the SQLite migrations); the scanner reads it from
the commit it analyses.
SonarCloud runs in CI, with the repository secret SONAR_TOKEN (a SonarCloud
token that may analyse the project). Its automatic analysis must stay off
(project Administration > Analysis Method): with both on, every CI scan fails.
Commits that touch only what the data jobs write (data/, games/, the
.jsonl queues and logs under scripts/) are not scanned. A pull request from
a fork or from Dependabot gets no repository secrets, so its scan job is
skipped; giving Dependabot its own SONAR_TOKEN (Settings > Secrets >
Dependabot) would have its pull requests analysed too.
Before the scan the job runs both test suites with coverage: pytest with
--cov (configured in pyproject.toml, written to coverage.xml) and
npm run test:coverage in web/ (configured in vite.config.ts, written to
web/coverage/lcov.info). SonarCloud's default "Sonar way" quality gate asks
for 80% coverage on new code (it ignores that condition below 20 new lines),
so a pull request that adds code its tests do not reach fails that check. To
see the figure locally, run
npm run test:coverage in web/, or
python -m pytest scripts/tests --cov after installing requirements-test.txt.
A red "Workers Builds" check on a PR branch is usually not yours
Cloudflare posts its own check alongside those. On a pull-request branch it has
been seen failing with zero duration — started_at equal to completed_at,
so nothing was compiled and there is no log reachable from GitHub — while the
identical commits built and deployed from main minutes later. Measured on
PR #130 (2026-09-20), twice.
Before spending time on it, look at the GitHub Actions check job: it already
runs the same npm run build, verify-dist.mjs and wrangler deploy --dry-run. If that is green, the build is sound and the Cloudflare check is
about the preview build, not your diff. The only place the real answer lives is
the build log in the Cloudflare dashboard, which the check links to.
Rolling back
Roll back the Worker deployment in the Cloudflare dashboard (Workers → free-steam-games-list → Deployments). Reverting the commit also works but takes a full build cycle.
GitHub Pages is not a fallback. It now serves only a redirect to this
domain; the app cannot run there because it is built with base: "/".
Secrets
wrangler.jsonc holds no secrets — only the D1 database_id, which is an
account-scoped identifier and safe to commit. Anything sensitive goes through
npx wrangler secret put: the GitHub App's three (see ADMIN.md)
and TURNSTILE_SECRET for the human check (see
SECURITY_SETUP.md section 12). The Worker declares them
in web/worker/env.d.ts.
For wrangler dev, put local values in web/.dev.vars (gitignored);
web/.dev.vars.example holds Cloudflare's always-pass Turnstile test secret.
Cost notes
Images. AVIF copies of the header art are minted by the cron into the R2
bucket f2p-media (web/worker/lib/img-mint.ts); /img/* only reads them, so
requests cannot spend anything - there is nothing for an allowlist to guard.
Images Paid bills $0.50 per 1,000 unique transformations after 5,000 a month
and has no spend cap; IMG_TRANSFORM_MONTHLY_CAP (a D1 counter) is the
cap. See SECURITY_SETUP.md section 5.
The bucket must exist before any deploy that binds it. wrangler deploy
fails with code 10085 otherwise (the old Worker stays live). It was created
with npx wrangler r2 bucket create f2p-media; keep its r2.dev URL disabled
and attach no custom domain - the Worker is the only reader.
R2 stays inside the free tier: ~11k objects at ~3-18 KB, about 12 list calls per cron tick only while minting, and reads only on an edge-cache miss.
Shard compression is a dashboard setting. Cloudflare does not compress
application/x-ndjson on its own, so the plain shards went out uncompressed
(~9 MiB per full load) until the Compression Rule ndjson-shards was added on
2026-10-02: Rules → Compression Rules, http.request.uri.path.extension eq "jsonl" → Custom: Brotli, Gzip. It applies to Worker responses (data_001:
1,497,828 → 225,826 bytes). The packed /api/data/p1/*.bin files are
compressed before they are encrypted and are deliberately not .jsonl, so the
rule never touches them.