CI and Deployment

The continuous-integration and deployment workflows that verify and publish repository surfaces.

CI jobs and artifacts

.github/workflows/ci.yml runs on pull requests and pushes to main. Its current job names are validate, packed-host-matrix, packed-host-install, demo-sites-build, demo-editors-build, demo-editors-batch, doc-site-build, and four styleguide artifact jobs.

The validation job's browser steps consume prepared artifacts and never rebuild them. demo:build-sites runs before the SiteProject and demos lanes, while demo:build-editors and the test:browser:demo-editor lane cover the four per-host editor artifacts. The separate doc-site-build job builds and verifies doc/dist before it uploads the documentation artifact; the production matrix consumes that exact SHA-named artifact. The validation-gates and browser-lanes pages explain the local equivalents and port ownership.

Trusted-run deployment

.github/workflows/hosted-demo-deploy.yml is an independent production workflow. Its automatic trigger is only a successful CI workflow run for a push to main in this repository. A manual dispatch provides target (all or one registry key), the CI run_id and full sha; the same guard still verifies the run through the GitHub API and checks that origin/main has not moved.

The production matrix contains thirteen current hosted targets. Dispatching with target: all (the default) selects every target once; selecting a registry key runs only that target.

The doc and all four *-sg targets are multi-page static sites. Keep each target key, Worker, config, domain, artifact directory, manifest, and CI artifact name aligned with the registry. Both verifyArtifact hooks directly use verifyDocSiteArtifact, and liveRoutes reads each manifest's routes. The routeFile and assetUrl hooks select each page's own HTML and canonical asset URL for extensionless and trailing-slash pages; see the live delivery contract. Static demo builds and disposable editor builds retain their own manifest contracts and artifact directories; the editor build is per-host and uses the demo-editor kind rather than a shared sample. Local doc builds may omit sourceRevision, but production preflight requires the full expected SHA and the same recorded artifact revision before Wrangler.

Sample's doc-site artifact keeps the root pnpm sg:build-site command. Shop, Landing and Blog use pnpm sg:build-styleguide <shop-sg|landing-sg|blog-sg>; pnpm sg:build-styleguides builds all four catalogs serially. Each standalone host has its own frozen lockfile and target-specific artifact directory. Their new Workers use the existing missing-Worker path to bind their configured domains after main CI.

Rollout sequence

Each matrix leg follows the same guarded sequence. The deployment script's preflight captures remote state before it runs the non-mutating Wrangler dry run, so the rollback precondition is known before any upload:

1. Guard. Load the guard from a fresh trusted main checkout. Require a successful same-repository main CI push (or validate the equivalent manual inputs), the exact full SHA, and a current origin/main.

2. Download. Download only the target's <prefix>-<sha> artifact from the selected CI run.

3. Verify. Verify every artifact byte, manifest, source identity, route list, and target-specific contract before Cloudflare access.

4. Preflight. Require deployment credentials, run wrangler whoami, and resolve the target config before any mutation.

5. Capture. Inspect the target's current state. Require the current deployment to be one 100% version and save that exact active version as the rollback target. Split traffic, missing rollback state, or partial Cloudflare state fails closed.

6. Dry run. Run wrangler deploy --dry-run --no-bundle with the verified directory and target config.

7. Upload. Use wrangler versions upload for the verified directory and retain the version ID returned by that upload.

8. Activate. Activate only that returned version ID at 100%; never infer an ID from an older versions list entry.

9. Live check. Fetch the manifest, every emitted asset, and every target route over bounded HTTPS requests, checking bytes, checksums, MIME types, and the active version.

10. Rollback. If live verification fails, roll back only while the exact uploaded version remains active. A successful rollback still leaves the job failed so the incident remains visible.

There is one first-Worker exception. When both deployments list and versions list report that a target Worker does not exist, a plain wrangler deploy creates the Worker, uploads its verified artifact, and binds its custom domain. It has no prior rollback target. Any other missing-state combination fails before mutation; a first-deploy live failure is reported red because there is no prior Worker to restore.

Secrets and environment boundaries

Pull-request validation has no Cloudflare secrets. The production step receives only the existing deployment credentials after the trusted-run guard and artifact checks: a Cloudflare API token (CLOUDFLARE_API_TOKEN or CLOUDFLARE_TOKEN) and CLOUDFLARE_ACCOUNT_ID. Missing or partial credentials fail visibly. Local Wrangler OAuth sessions may be useful for read-only checks, but must never be copied into repository or workflow secrets.

For the target contracts, live-check details, and manual recovery rules, use the hosted-demo operator guide.