Skip to content

operations.md

Latest commit

 

History

History
132 lines (107 loc) · 7.4 KB

operations.md

File metadata and controls

132 lines (107 loc) · 7.4 KB
Raw

Production availability checks

The Check production availability GitHub workflow checks the public site at minutes 7, 22, 37 and 52 of every hour. It uses Node 24 without installing dependencies, deploying anything, or accessing Cloudflare credentials.

The checks cover the Astro home and download pages, a classic URL redirect with its query string, the users archive, robots rules, the documentation sitemap, latest and versioned reference URLs, and PDF headers plus a 16-byte range. When the selected production DOC_REVISIONS entry is present, they also check the modeling manual and its search JavaScript. Version and revision come from workers/docs/wrangler.jsonc; update that configuration when promoting documentation. Each run makes ten requests, or twelve with the modeling manual, and caps each response read at 1 MB. It never downloads the complete PDF.

Transient failures get two retries, twenty seconds apart. Persistent failures fail the workflow and leave the failing path in its log. Check the failed path, the latest Pages and Worker deployments, and Cloudflare Workers logs. A version or revision mismatch can mean the checked-in promotion has not reached production yet. Use the deployment runbook for rollback; this workflow never changes traffic automatically.

Run manually

From the website checkout:

node scripts/check-availability.mjs
gh workflow run availability.yml --repo Gecode/gecode.github.io --ref main
gh run list --repo Gecode/gecode.github.io --workflow availability.yml --limit 5

Use scripts/docs/smoke-worker.mjs for the broader documentation checks after a deployment. The scheduled checks deliberately use a smaller request set.

Make failures reach a maintainer

The responsible maintainer must enable GitHub Actions email or web notifications and select failed workflows only. Scheduled-run notifications go to the user who created or last changed the schedule, or who re-enabled it. Repository workflow success alone does not establish that anyone receives failure alerts. Confirm that maintainer's settings before relying on this workflow. See GitHub workflow notifications.

On 5 September 2026, the authenticated zayenz account's settings were checked: Actions email notifications were enabled for failed workflows only. Keep that account as the schedule owner, or verify the replacement owner's settings.

GitHub schedules can be delayed or dropped under load. Public-repository schedules are automatically disabled after sixty days without repository activity. Check that this workflow remains enabled during routine maintenance; re-enable it when necessary. This is a periodic availability check, with no guaranteed detection time, and cannot detect every regional or intermittent failure. See GitHub schedule limitations.

Cloudflare's budget notification remains separate from availability monitoring. A passive origin alert can complement these checks, but it does not cover every failure generated by the documentation Worker or R2. A Workers Observability notification also needs an actual alert rule; the notification destination alone does not monitor errors.

CDN cache policy

The Cloudflare zone's Browser Cache TTL is set to Respect Existing Headers. Two active Cache Rules refine that default:

  • Cache immutable Astro assets matches www.gecode.dev/_astro/*, makes the response cache-eligible, and sets both edge and browser TTLs to one year.
  • Cache website HTML and redirects matches the apex host and non-documentation website HTML paths on www. It makes those responses cache-eligible, respects origin cache headers, and uses Cloudflare's status-code TTL when the origin sends no cache header.

Keep /doc* out of the website rule. The documentation Worker owns its cache policy. The prepared Workers Cache change gives selected routes and aliases thirty days of edge freshness plus seven days of stale-while-revalidate, while browsers retain one-day freshness. Sitemaps and robots.txt retain five-minute browser freshness. Explicit revisions retain a one-year policy. See the Worker runbook for the policy and staging checks. On 30 September 2026, the change was deployed to staging from PR #13. The updated staging deployment and smoke checks passed. A fresh URL returned MISS, HIT, HIT with Cache-Control: public, max-age=86400. An earlier probe confirmed one Worker execution for three requests. The smoke check accepts native Workers Cache's 206 response to HEAD with Range and checks plain HEAD separately. Production deployment remains subject to the protected environment's approval. Short-TTL SWR and live revision rollback have not yet been exercised against the native cache.

Ordinary zone caching runs after Worker routing. Workers Cache sits before execution, but its hits still count as Worker requests. Neither response headers nor a zone Cache Rule removes that request charge. Measure execution avoidance separately from billable requests and zone cache hits.

Option: a CDN ahead of the Worker

An external CDN can avoid Cloudflare requests on cache hits. A concrete option is Fastly Full Site Delivery at www.gecode.dev, with documentation misses sent to a dedicated Cloudflare Worker origin hostname and website misses sent to GitHub Pages. This is a researched option, not a provisioned or tested service.

Use Fastly's Surrogate-Control header for the long edge TTL and SWR policy; Cloudflare's edge-only header does not configure Fastly. Enable origin shielding to share cache fills across locations. Tag mutable documentation responses and soft-purge those tags after release promotion or rollback. Deploying the Worker alone cannot invalidate the external cache.

Before switching public DNS, verify backend Host/TLS settings, public canonical URLs and redirects, analytics injection and /e/ forwarding, query handling, PDF ranges, SWR, and release invalidation on a preview hostname. Keep private R2 access through the Worker. Do not point the CDN backend at its own public hostname or expose the existing bucket's staging and manifest keys. Select the provider and billing arrangement before provisioning this separate rollout.

Email forwarding

The email Worker waits for every configured forward to finish and reports any forwarding failure. Native Worker logging is enabled; the handler does not log message bodies. Deploy it separately from the website and documentation:

gh workflow run workers.yml --repo Gecode/gecode.github.io --ref main \
  -f operation=deploy -f environment=production -f worker=email

The routing tests cover address selection and partial forwarding failure. They do not establish inbox delivery. Use Cloudflare Email Routing delivery analytics for that check; its zone-level Analytics Read permission is separate from the website deployment token. A failed availability run does not diagnose mail delivery, because the public HTTP checks exercise only the website.