cfsite

Gotchas

Each of these cost time once. The fix is already in this repository.

Cloudflare

The first deploy will not replace a DNS record

If the hostname already has an A, AAAA or CNAME record, wrangler deploy fails: already has externally managed DNS records [code: 100117]. Delete the record and re-run the job. Cloudflare then creates its own record and certificate.

wrangler preview needs "previews": {}

Without the (empty) block in wrangler.jsonc the preview upload fails.

A compatibility date that is too new

A compatibility_date newer than the local runtime breaks wrangler dev. Use a date a few days old, not today's.

wrangler errors hidden in CI

In a step that runs with bash -e, a failing wrangler command shows only exit 1. Capture the exit code and print wrangler's output yourself, as the deploy workflow does.

GitHub Actions

ubuntu-latest moves

ubuntu-latest is Ubuntu 26.04, which ruby/setup-ruby has no older Ruby builds for. Jobs that build with Ruby (Jekyll) pin ubuntu-24.04.

The QR code tool waits for input

npx qrcode reads the text from standard input when it is not run in a terminal, and hangs in CI. Call it with < /dev/null; it then takes the text from its arguments.

Playwright browser downloads

A first download of a new Playwright browser version can be slow or hang, and installing its system packages sometimes takes ten minutes on a runner. Keep Playwright pinned, and give the job a timeout.

No secrets for Dependabot and forks

Their pull requests run without repository secrets. Check for the token (secrets.CLOUDFLARE_API_TOKEN != '') and skip the preview, instead of letting the job fail.

Artifacts are zips

By default an uploaded artifact downloads as a zip. For a single HTML report, actions/upload-artifact v7 with archive: false keeps it a plain file.

Testing

Pages with live data

A page that renders data fetched at load time differs between the preview and production. In the visual test, fetch each API response once with Playwright's page.route and replay it to both sides, and freeze the clock with page.clock.setFixedTime. Only on those pages: a frozen clock can hang pages that wait for time to pass.

Lighthouse performance is noisy

The same preview can score 100 and then 53. Use the median of several runs, and do not compare CI scores with a laptop's.

Local Playwright runs that never return

timeout 120 npx playwright test can wait forever for npx; use timeout -k 5 120.