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.