Static Site Generators in Production

Canary Releases for Static Sites

Static sites are already safer to deploy than most software: deploys are atomic, previous versions stay available, and rolling back takes seconds. What they lack is a gap between "deployed" and "everyone has it". A deploy that breaks the search box on Safari, doubles the JavaScript bundle or ships a CSS change that hides the navigation on small screens reaches all readers at once, and stays live until someone notices and rolls back.

A canary release closes that gap. The new build goes to a small share of readers first — say 5% — while metrics compare them with everyone else. If errors, missing assets or Core Web Vitals get worse, the canary is stopped before most readers ever see it. This guide shows how to run canaries for static sites with Cloudflare Workers gradual deployments or a small edge split, how to keep readers on one version, and what to measure. It is part of Rollbacks and Deploy Safety for Static Sites.

Prerequisites

How a Canary Works

Canary traffic split for a static site Incoming requests reach an edge router. Visitors without a version cookie are assigned 95 percent to the stable version and 5 percent to the canary, and the choice is stored in a cookie. Later requests follow the cookie. Both versions send RUM beacons tagged with their version to a comparison dashboard. Sticky 95 / 5 split with version-tagged metrics requests edge router cookie or random assign stable (95%) version a1b2c3 canary (5%) version d4e5f6 RUM compare errors, vitals the version cookie keeps each reader's HTML and assets from the same build
Stickiness and version-tagged metrics are what make a canary safe and readable.

Two properties matter more than the split itself. The assignment must be sticky: a reader who gets the canary's HTML must also get the canary's CSS and JavaScript, or pages with hashed filenames break. And metrics must be tagged by version, so the canary group can be compared with the stable group rather than with last week.

Option 1: Cloudflare Workers Gradual Deployments

Sites served by a Worker with static assets can use Workers' built-in versions. wrangler versions upload creates a new version without sending traffic to it; wrangler versions deploy splits traffic between versions by percentage:

npx wrangler versions upload --message "$(git log -1 --format=%s)"
npx wrangler versions deploy <new-version-id>@5% <current-version-id>@95% -y
# later, after checks
npx wrangler versions deploy <new-version-id>@100% -y

To make the split sticky, set version affinity: a request header or cookie that Cloudflare uses to keep the same client on the same version. Set Cloudflare-Workers-Version-Overrides for testing a specific version, and enable session affinity via a request key so a reader stays on the version they first received. Each version's static assets are served with that version, so HTML and assets always match. See Migrating from Cloudflare Pages to Workers Static Assets if the site is still on Pages.

On other hosts, an edge function in front of two deployments does the same. Deploy the canary build to a separate origin or path — a preview URL works — and route by cookie:

export default async (request: Request) => {
  const cookie = request.headers.get('Cookie') ?? '';
  let version = /site_version=(stable|canary)/.exec(cookie)?.[1];
  const assign = !version;
  if (!version) version = Math.random() < 0.05 ? 'canary' : 'stable';

  const origin = version === 'canary' ? 'https://canary.example-preview.com' : 'https://stable.example-origin.com';
  const url = new URL(request.url);
  const res = await fetch(new Request(origin + url.pathname + url.search, request));
  const out = new Response(res.body, res);
  if (assign) out.headers.append('Set-Cookie', `site_version=${version}; Path=/; Max-Age=86400; Secure; SameSite=Lax`);
  out.headers.set('X-Site-Version', version);
  return out;
};

Add Vary: Cookie or bypass the CDN cache for HTML during the canary, or the CDN may serve one version's HTML to both groups. Hashed assets can stay cacheable: their names differ between builds, so they never collide. Netlify's split testing between branch deploys implements the same pattern without code.

What to Measure

Tag every RUM beacon and error report with the build version. Expose it in the HTML at build time — a <meta name="build" content="d4e5f6"> tag — and read it in the monitoring snippet. Then compare the two groups on:

  • JavaScript error rate per page view.
  • 404 rate on asset requests, which catches missing or misnamed files.
  • Core Web Vitals — LCP, INP and CLS at the 75th percentile.
  • Key actions — search usage, sign-ups, clicks on the main call to action.
A canary that failed its comparison During a two-hour canary, the stable version had 0.2 JavaScript errors per 1,000 page views and INP p75 of 140 milliseconds. The canary had 6.8 errors per 1,000 views and INP of 310 milliseconds, both beyond the thresholds, so it was stopped and traffic returned to stable. Stable vs canary, first two hours 0.2 6.8 JS errors / 1,000 views 140 ms 310 ms INP p75 blue: stable · red: canary (5% of traffic) — stopped at 2 h, 95% of readers never affected
Comparing the two groups side by side made the regression obvious within hours.

Also give the team a way to see the canary on demand. A query parameter or header that forces the canary version — Workers' version override header, or a ?version=canary rule in the edge router that sets the cookie — lets reviewers and support staff check the new build in production before it reaches everyone, without waiting to be assigned by chance.

Decide thresholds before the canary starts — for example, error rate no more than 1.5 times stable, INP no more than 20% worse — so the decision to promote or stop is mechanical, not a debate.

Automating Promotion

A canary that someone has to remember to promote tends to sit at 5% for days. Automate it in the deploy workflow: after deploying at 5%, wait a fixed time — 30 minutes to a few hours depending on traffic — query the monitoring API for the comparison, and either promote to 100% or roll back. Low-traffic sites may need a larger canary share or a longer wait to collect enough data for a meaningful comparison; a canary with 40 page views proves nothing.

Automated canary timeline After merge, the new version is uploaded and deployed at 5 percent. After a two-hour observation window, the workflow queries the monitoring API. If all metrics are within thresholds, it promotes to 100 percent. If any metric breaches, it sets the canary to 0 percent and opens an issue with the comparison. Merge to full rollout without a human in the loop merge deploy at 5% versions deploy observe 2 h query RUM API within thresholds promote to 100% threshold breached 0% + open an issue content-only builds can skip straight to 100% through a separate fast path
Thresholds agreed in advance turn the promote-or-stop decision into a script.

Record each canary's outcome and comparison numbers in the deployment log. Over a few months that history shows whether the thresholds are too loose (regressions slipping through) or too tight (healthy releases stopped), and gives a factual basis for adjusting them.

Measured Impact

A documentation site with about 400,000 monthly page views moved its production deploys to Workers gradual deployments with a 5% canary for two hours and automatic promotion. In the first six months, 3 of 140 deploys were stopped by the canary: a search script that threw on Safari, a bundle that doubled in size after a dependency update, and a CSS change that hid the sidebar on tablets. Each affected about 5% of readers for under two hours, where previously such issues had typically been live for everyone for half a day before a reader reported them.

Pitfalls & Rollback

  • Non-sticky routing. Mixed versions break hashed assets; always pin readers with a cookie or affinity key.
  • Cached HTML across versions. Vary on the version cookie or skip HTML caching during the canary.
  • Untagged metrics. Without a version tag, the canary's problems are diluted into site-wide averages.
  • Content deploys. A typo fix does not need two hours of canary; allow a fast path for content-only builds.
  • Rollback: set the canary share to 0% or deploy the stable version at 100%; readers with the canary cookie return on their next request.

Conclusion

Canary releases give static sites the one safety property atomic deploys lack: a bad build reaches a few readers, not all of them. Split traffic with Workers gradual deployments or a small cookie-based edge router, keep each reader on one version, tag metrics with the build version, compare the groups against thresholds agreed in advance, and promote or roll back automatically. The cost is a short delay before a release reaches everyone.

FAQ

Why would a static site need canary releases?

Static deploys are atomic and easy to roll back, but a bad deploy still reaches every reader until someone notices. A canary sends a small share of traffic to the new version first, so broken JavaScript, a CSS regression or a performance drop affects a few percent of readers and is caught by metrics before full rollout.

How do I keep a reader on the same version during a canary?

Assign each visitor to a version once, store the choice in a cookie, and route later requests by that cookie. Otherwise a reader can load HTML from one version and CSS or JavaScript from the other, which breaks pages with hashed asset names.

What should I monitor during a canary?

Compare the canary with the stable version on JavaScript error rate, 404 rate for assets, Core Web Vitals from real users, and key conversions such as search usage or sign-ups. Tag every beacon with the version so the two groups can be compared directly.

Which platforms support canary releases for static sites?

Cloudflare Workers offers gradual deployments that split traffic between versions by percentage. Netlify offers split testing between branch deploys. On other hosts, a small edge function or CDN rule that routes by cookie to two origins or path prefixes achieves the same.