diff --git a/.github/scripts/pages-static-assets.mjs b/.github/scripts/pages-static-assets.mjs
new file mode 100644
index 000000000..ca5ea6867
--- /dev/null
+++ b/.github/scripts/pages-static-assets.mjs
@@ -0,0 +1,87 @@
+import { appendFileSync, cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { resolve, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { deploymentMatrix } from "./pages-projects.mjs";
+
+export function staticAssetsMatrix(projects, targets) {
+ const pages = deploymentMatrix(projects).include;
+ const configured = JSON.parse(targets || "[]");
+ if (!Array.isArray(configured) || configured.length > pages.length) throw new Error("Invalid static asset targets");
+ const seenProjects = new Set();
+ const seenWorkers = new Set();
+ const seenDomains = new Set();
+ return { include: configured.map((target) => {
+ if (!target || Object.keys(target).some((key) => !["project", "worker", "domains"].includes(key))) throw new Error("Invalid static asset target");
+ const page = pages.find((entry) => entry.project === target.project);
+ if (!page || typeof target.worker !== "string" || !/^[a-z0-9][a-z0-9-]{0,62}$/.test(target.worker)) throw new Error("Unknown project or invalid Worker name");
+ if (!Array.isArray(target.domains) || target.domains.length > 10) throw new Error("Explicit domains required");
+ for (const domain of target.domains) {
+ if (typeof domain !== "string" || domain.length > 253 || !/^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/.test(domain) || seenDomains.has(domain)) throw new Error("Invalid or duplicate custom domain");
+ seenDomains.add(domain);
+ }
+ if (seenProjects.has(target.project) || seenWorkers.has(target.worker)) throw new Error("Duplicate static asset target");
+ seenProjects.add(target.project);
+ seenWorkers.add(target.worker);
+ return { ...page, worker: target.worker, domains: target.domains };
+ }) };
+}
+
+export function prepareStaticAssets({ target, sourceRoot, destination, sourceSha, release }) {
+ if (!/^[a-f0-9]{40}$/.test(sourceSha) || !/^v\d+\.\d+\.\d+$/.test(release)) throw new Error("Exact release identity required");
+ const output = resolve(sourceRoot, target.output_dir);
+ const dest = resolve(destination);
+ if (existsSync(dest)) throw new Error("Use a new artifact directory");
+ let files = 0;
+ function check(path) {
+ const stat = lstatSync(path);
+ if (stat.isSymbolicLink()) throw new Error("Static artifacts must not contain symlinks");
+ if (stat.isDirectory()) {
+ for (const entry of readdirSync(path)) check(join(path, entry));
+ } else if (!stat.isFile() || stat.size > 25 * 1024 * 1024 || ++files > 19999) {
+ throw new Error("Artifact exceeds Workers Free asset limits");
+ }
+ }
+ check(output);
+ if (!existsSync(join(output, "index.html")) || !existsSync(join(output, "_headers"))) throw new Error("Frontend index and response headers required");
+ if (existsSync(join(output, "_worker.js")) || existsSync(join(output, "_routes.json"))) throw new Error("Only static artifacts are supported");
+ mkdirSync(dest, { recursive: true });
+ cpSync(output, join(dest, "assets"), { recursive: true });
+ if (target.app === "admin") {
+ const redirects = join(dest, "assets", "_redirects");
+ if (existsSync(redirects)) {
+ const rules = readFileSync(redirects, "utf8").split("\n").map((line) => line.trim()).filter((line) => line && !line.startsWith("#"));
+ if (rules.length !== 1 || !/^\/\*\s+\/index\.html\s+200$/.test(rules[0])) throw new Error("Review changed admin redirect rules before publishing static assets");
+ // The asset platform's SPA mode replaces the Pages-only catch-all rewrite.
+ rmSync(redirects);
+ }
+ }
+ mkdirSync(join(dest, "assets", ".well-known"), { recursive: true });
+ writeFileSync(join(dest, "assets", ".well-known", "warmbly-release.json"), JSON.stringify({ release, sourceSha, app: target.app, project: target.project }) + "\n");
+ const config = {
+ name: target.worker,
+ compatibility_date: "2025-10-11",
+ workers_dev: false,
+ preview_urls: false,
+ assets: { directory: "./assets", html_handling: "auto-trailing-slash", not_found_handling: target.app === "admin" ? "single-page-application" : "404-page" },
+ routes: target.domains.map((pattern) => ({ pattern, custom_domain: true })),
+ };
+ writeFileSync(join(dest, "wrangler.json"), JSON.stringify(config, null, 2) + "\n");
+ return config;
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+ try {
+ const matrix = staticAssetsMatrix(process.env.CLOUDFLARE_PAGES_PROJECTS, process.env.CLOUDFLARE_STATIC_ASSETS_TARGETS);
+ if (["prepare", "prepare-if-configured"].includes(process.argv[2])) {
+ const target = matrix.include.find((entry) => entry.project === process.env.CLOUDFLARE_PAGES_PROJECT_NAME);
+ if (!target && process.argv[2] === "prepare") throw new Error("Project is not configured for static assets");
+ if (process.env.GITHUB_OUTPUT) appendFileSync(process.env.GITHUB_OUTPUT, `enabled=${Boolean(target)}\n`);
+ if (target) prepareStaticAssets({ target, sourceRoot: process.cwd(), destination: process.env.STATIC_ASSETS_ARTIFACT_DIR, sourceSha: process.env.SOURCE_SHA, release: process.env.RELEASE_TAG });
+ } else {
+ appendFileSync(process.env.GITHUB_OUTPUT, `matrix=${JSON.stringify(matrix)}\nenabled=${matrix.include.length > 0}\n`);
+ }
+ } catch {
+ console.error("::error::Invalid static asset configuration or artifact. Require unique configured Pages projects, Worker names, explicit domains and an exact release identity.");
+ process.exitCode = 1;
+ }
+}
diff --git a/.github/scripts/pages-static-assets.test.mjs b/.github/scripts/pages-static-assets.test.mjs
new file mode 100644
index 000000000..e96988949
--- /dev/null
+++ b/.github/scripts/pages-static-assets.test.mjs
@@ -0,0 +1,77 @@
+import assert from "node:assert/strict";
+import { cpSync, existsSync, mkdtempSync, mkdirSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+import { staticAssetsMatrix, prepareStaticAssets } from "./pages-static-assets.mjs";
+
+const projects = JSON.stringify([{ app: "web", project: "dashboard" }, { app: "admin", project: "admin" }, { app: "docs", project: "docs" }]);
+const configured = [{ project: "dashboard", worker: "warmbly-dashboard", domains: ["stage.warmbly.com"] }];
+const sha = "a".repeat(40);
+
+test("static assets are disabled unless exact Pages projects are configured", () => {
+ assert.deepEqual(staticAssetsMatrix(projects), { include: [] });
+ const target = staticAssetsMatrix(projects, JSON.stringify(configured)).include[0];
+ assert.equal(target.output_dir, "web/dist");
+ assert.equal(target.environment, "dashboard-production");
+ assert.equal(target.worker, "warmbly-dashboard");
+ assert.deepEqual(target.domains, ["stage.warmbly.com"]);
+});
+
+test("rejects unknown projects, paths, domains, duplicate mappings and overrides", () => {
+ for (const value of [null, {}, [null], [{ ...configured[0], project: "unknown" }], [{ ...configured[0], output_dir: "/tmp" }], [{ ...configured[0], worker: "../worker" }], [{ ...configured[0], domains: ["*.warmbly.com"] }], [{ ...configured[0], domains: ["stage.warmbly.com/path"] }], [{ ...configured[0], domains: ["stage.warmbly.com", "stage.warmbly.com"] }], [configured[0], configured[0]], [configured[0], { project: "admin", worker: "admin", domains: ["stage.warmbly.com"] }]]) {
+ assert.throws(() => staticAssetsMatrix(projects, JSON.stringify(value)));
+ }
+});
+
+function fixture(app, fn) {
+ const root = mkdtempSync(join(tmpdir(), "static-assets-"));
+ try {
+ const target = staticAssetsMatrix(projects, JSON.stringify([{ project: app === "web" ? "dashboard" : app, worker: "fixture", domains: [] }])).include[0];
+ const output = join(root, target.output_dir);
+ mkdirSync(output, { recursive: true });
+ writeFileSync(join(output, "index.html"), "
Warmbly fixture
");
+ for (const name of ["_headers", "_redirects", "404.html"]) {
+ try { cpSync(new URL(`../../${app}/public/${name}`, import.meta.url), join(output, name)); } catch (error) { if (error.code !== "ENOENT") throw error; }
+ }
+ fn({ root, target, output, destination: join(root, "artifact") });
+ } finally { rmSync(root, { recursive: true, force: true }); }
+}
+
+test("publishes only assets and preserves exact route/header/404 files and release identity", () => {
+ fixture("web", ({ root, target, output, destination }) => {
+ const config = prepareStaticAssets({ target, sourceRoot: root, destination, sourceSha: sha, release: "v0.6.74" });
+ assert.equal(config.main, undefined);
+ assert.equal(config.workers_dev, false);
+ assert.equal(config.preview_urls, false);
+ assert.equal(config.assets.not_found_handling, "404-page");
+ assert.deepEqual(config.routes, []);
+ for (const name of ["index.html", "_headers", "_redirects", "404.html"]) assert.deepEqual(readFileSync(join(output, name)), readFileSync(join(destination, "assets", name)));
+ assert.deepEqual(JSON.parse(readFileSync(join(destination, "assets/.well-known/warmbly-release.json"))), { release: "v0.6.74", sourceSha: sha, app: "web", project: "dashboard" });
+ assert.throws(() => prepareStaticAssets({ target, sourceRoot: root, destination, sourceSha: sha, release: "v0.6.74" }));
+ });
+});
+
+test("admin preserves its SPA fallback and domains are explicit custom-domain bindings", () => {
+ fixture("admin", ({ root, target, destination }) => {
+ const config = prepareStaticAssets({ target: { ...target, domains: ["admin-stage.warmbly.com"] }, sourceRoot: root, destination, sourceSha: sha, release: "v0.6.74" });
+ assert.equal(config.assets.not_found_handling, "single-page-application");
+ assert.equal(existsSync(join(destination, "assets", "_redirects")), false);
+ assert.deepEqual(config.routes, [{ pattern: "admin-stage.warmbly.com", custom_domain: true }]);
+ });
+});
+
+test("refuses unpinned releases, executable Pages functions and symlink artifacts", () => {
+ for (const kind of ["sha", "tag", "function", "symlink"]) fixture("web", ({ root, target, output, destination }) => {
+ if (kind === "function") writeFileSync(join(output, "_worker.js"), "export default {}");
+ if (kind === "symlink") symlinkSync("/etc/hosts", join(output, "outside"));
+ assert.throws(() => prepareStaticAssets({ target, sourceRoot: root, destination, sourceSha: kind === "sha" ? "main" : sha, release: kind === "tag" ? "latest" : "v0.6.74" }));
+ });
+});
+
+test("changed admin redirect behavior requires explicit review", () => {
+ fixture("admin", ({ root, target, output, destination }) => {
+ writeFileSync(join(output, "_redirects"), "/old /new 301\n");
+ assert.throws(() => prepareStaticAssets({ target, sourceRoot: root, destination, sourceSha: sha, release: "v0.6.74" }));
+ });
+});
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index ae87b7764..d39b16784 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -110,6 +110,7 @@ jobs:
- 'scripts/check-cli-installer.sh'
- 'scripts/build-cli.sh'
pages:
+ - '.github/workflows/static-assets.yml'
- 'deploy/cloudflare/**'
- '.github/scripts/pages-*'
- '.github/workflows/release.yml'
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index d8645eac6..ee6170452 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -657,3 +657,33 @@ jobs:
--branch "$CLOUDFLARE_PAGES_PRODUCTION_BRANCH" \
--commit-hash "$GITHUB_SHA" \
--commit-message "$RELEASE_TAG"
+
+ - name: Prepare optional static asset mirror
+ id: static-assets
+ if: vars.CLOUDFLARE_STATIC_ASSETS_DEPLOY_ENABLED == 'true'
+ env:
+ CLOUDFLARE_PAGES_PROJECTS: ${{ vars.CLOUDFLARE_PAGES_PROJECTS }}
+ CLOUDFLARE_STATIC_ASSETS_TARGETS: ${{ vars.CLOUDFLARE_STATIC_ASSETS_TARGETS }}
+ SOURCE_SHA: ${{ github.sha }}
+ RELEASE_TAG: ${{ github.ref_name }}
+ run: |
+ export STATIC_ASSETS_ARTIFACT_DIR="$RUNNER_TEMP/static-assets"
+ node .github/scripts/pages-static-assets.mjs prepare-if-configured
+
+ - name: Publish the same artifact to the configured static asset host
+ if: steps.static-assets.outputs.enabled == 'true'
+ env:
+ CLOUDFLARE_ACCOUNT_ID: ${{ vars.CLOUDFLARE_STATIC_ASSETS_ACCOUNT_ID }}
+ CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_STATIC_ASSETS_API_TOKEN }}
+ WRANGLER_SEND_METRICS: "false"
+ run: |
+ test -n "$CLOUDFLARE_ACCOUNT_ID"
+ test -n "$CLOUDFLARE_API_TOKEN"
+ pnpm dlx wrangler@4.45.0 deploy --config "$RUNNER_TEMP/static-assets/wrangler.json"
+
+ - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+ if: steps.static-assets.outputs.enabled == 'true'
+ with:
+ name: static-assets-${{ matrix.project }}-${{ github.ref_name }}-${{ github.run_id }}
+ path: ${{ runner.temp }}/static-assets
+ retention-days: 30
diff --git a/.github/workflows/static-assets.yml b/.github/workflows/static-assets.yml
new file mode 100644
index 000000000..0490d6f35
--- /dev/null
+++ b/.github/workflows/static-assets.yml
@@ -0,0 +1,116 @@
+name: Publish released static assets
+
+on:
+ workflow_dispatch:
+ inputs:
+ release_tag:
+ description: Existing stable release tag to rebuild (no new release)
+ required: true
+ type: string
+ expected_sha:
+ description: Full commit SHA of that release
+ required: true
+ type: string
+
+permissions:
+ contents: read
+
+concurrency:
+ group: release
+ cancel-in-progress: false
+
+jobs:
+ targets:
+ if: github.ref == 'refs/heads/main' && vars.CLOUDFLARE_STATIC_ASSETS_DEPLOY_ENABLED == 'true'
+ runs-on: ubuntu-latest
+ outputs:
+ matrix: ${{ steps.targets.outputs.matrix }}
+ enabled: ${{ steps.targets.outputs.enabled }}
+ steps:
+ - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+ with:
+ persist-credentials: false
+ - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+ with:
+ node-version: "22"
+ - run: node --test .github/scripts/pages-*.test.mjs
+ - id: targets
+ env:
+ CLOUDFLARE_PAGES_PROJECTS: ${{ vars.CLOUDFLARE_PAGES_PROJECTS }}
+ CLOUDFLARE_STATIC_ASSETS_TARGETS: ${{ vars.CLOUDFLARE_STATIC_ASSETS_TARGETS }}
+ run: node .github/scripts/pages-static-assets.mjs
+
+ publish:
+ needs: targets
+ if: needs.targets.outputs.enabled == 'true'
+ strategy:
+ fail-fast: false
+ matrix: ${{ fromJSON(needs.targets.outputs.matrix) }}
+ runs-on: ubuntu-latest
+ timeout-minutes: 30
+ environment: ${{ matrix.environment }}
+ env:
+ PAGES_APP: ${{ matrix.app }}
+ CLOUDFLARE_PAGES_PROJECT_NAME: ${{ matrix.project }}
+ SOURCE_SHA: ${{ inputs.expected_sha }}
+ RELEASE_TAG: ${{ inputs.release_tag }}
+ WRANGLER_SEND_METRICS: "false"
+ steps:
+ - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+ with:
+ fetch-depth: 0
+ persist-credentials: false
+ - name: Pin the existing release source
+ run: |
+ [[ "$RELEASE_TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]
+ [[ "$SOURCE_SHA" =~ ^[0-9a-f]{40}$ ]]
+ test "$(git rev-parse "refs/tags/$RELEASE_TAG^{commit}")" = "$SOURCE_SHA"
+ git merge-base --is-ancestor "$SOURCE_SHA" origin/main
+ git worktree add --detach "$RUNNER_TEMP/frontend-source" "$SOURCE_SHA"
+ - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+ with:
+ node-version: "22"
+ - name: Load existing public frontend configuration
+ env:
+ CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+ CLOUDFLARE_PAGES_ACCOUNT_ID: ${{ vars.CLOUDFLARE_ACCOUNT_ID }}
+ run: |
+ test -n "$CLOUDFLARE_API_TOKEN"
+ test -n "$CLOUDFLARE_PAGES_ACCOUNT_ID"
+ curl --fail --silent --show-error \
+ --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
+ "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_PAGES_ACCOUNT_ID/pages/projects/$CLOUDFLARE_PAGES_PROJECT_NAME" \
+ | node "$RUNNER_TEMP/frontend-source/.github/scripts/pages-production-config.mjs"
+ - uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4
+ with:
+ version: "11.9.0"
+ - name: Build the released frontend artifact
+ env:
+ APP_DIRECTORY: ${{ matrix.directory }}
+ BUILD_SCRIPT: ${{ matrix.build_script }}
+ VITE_SENTRY_RELEASE: ${{ inputs.release_tag }}
+ run: |
+ cd "$RUNNER_TEMP/frontend-source/$APP_DIRECTORY"
+ pnpm install --frozen-lockfile
+ pnpm run "$BUILD_SCRIPT"
+ - name: Prepare the configured static asset deployment
+ env:
+ CLOUDFLARE_PAGES_PROJECTS: ${{ vars.CLOUDFLARE_PAGES_PROJECTS }}
+ CLOUDFLARE_STATIC_ASSETS_TARGETS: ${{ vars.CLOUDFLARE_STATIC_ASSETS_TARGETS }}
+ run: |
+ export STATIC_ASSETS_ARTIFACT_DIR="$RUNNER_TEMP/static-assets"
+ cd "$RUNNER_TEMP/frontend-source"
+ node "$GITHUB_WORKSPACE/.github/scripts/pages-static-assets.mjs" prepare
+ - name: Publish assets without a request Worker
+ env:
+ CLOUDFLARE_ACCOUNT_ID: ${{ vars.CLOUDFLARE_STATIC_ASSETS_ACCOUNT_ID }}
+ CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_STATIC_ASSETS_API_TOKEN }}
+ run: |
+ test -n "$CLOUDFLARE_ACCOUNT_ID"
+ test -n "$CLOUDFLARE_API_TOKEN"
+ pnpm dlx wrangler@4.45.0 deploy --config "$RUNNER_TEMP/static-assets/wrangler.json"
+ - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+ with:
+ name: static-assets-${{ matrix.project }}-${{ inputs.release_tag }}-${{ github.run_id }}
+ path: ${{ runner.temp }}/static-assets
+ retention-days: 30
diff --git a/docs/content/docs/development/configuration.mdx b/docs/content/docs/development/configuration.mdx
index 837c5506a..b1a0d7d19 100644
--- a/docs/content/docs/development/configuration.mdx
+++ b/docs/content/docs/development/configuration.mdx
@@ -677,6 +677,46 @@ Stage each hostname, verify effective TLS and frontend responses, and retain the
Pages association and DNS needed for rollback before moving production traffic.
The deployment procedure is in `deploy/cloudflare/README.md`.
+### Optional hosted static assets
+
+Workers Static Assets can serve the same built frontend files directly, without a
+request Worker. This is a separate opt-in delivery path. The existing Pages
+projects remain the public build-configuration source and the rollback copy.
+Self-hosted containers and their configuration are unchanged.
+
+| GitHub variable or secret | What it does | Default |
+|---|---|---|
+| `CLOUDFLARE_STATIC_ASSETS_DEPLOY_ENABLED` | Set the repository variable to `true` to enable configured static asset deployments alongside release Pages uploads, and permit the manual frontend-only workflow | unset |
+| `CLOUDFLARE_STATIC_ASSETS_TARGETS` | Repository variable containing JSON entries with `project`, `worker` and explicit `domains`. Projects must already appear in `CLOUDFLARE_PAGES_PROJECTS`. Domains are Worker custom-domain bindings; use a staging domain before any production hostname | `[]` |
+| `CLOUDFLARE_STATIC_ASSETS_ACCOUNT_ID` | Cloudflare account that owns the Workers custom domains, configured in the corresponding frontend's GitHub environment | unset |
+| `CLOUDFLARE_STATIC_ASSETS_API_TOKEN` | GitHub environment secret permitting Workers asset deployment and the explicitly configured custom domains in that account | unset |
+
+For example, a staging entry is
+`[{"project":"dashboard-project","worker":"dashboard-assets-stage","domains":["assets-stage.example.com"]}]`.
+No wildcard domain is accepted. Empty domains publish an unattached artifact;
+`workers.dev` and preview URLs stay disabled. The publisher preserves
+`_headers` and the dashboard's `_redirects`. For admin it replaces the Pages
+catch-all rewrite with the platform's SPA fallback and keeps the other
+frontends' 404 behavior. It rejects symlinks, Pages Functions, files above 25 MiB
+and artifacts exceeding the Free plan's 20,000-file limit.
+
+The manual **Publish released static assets** workflow rebuilds an existing
+stable release using its tag and exact commit SHA. It does not create a tag,
+release, application deployment or worker-fleet update. It uses current public
+Pages configuration, so a rebuilt artifact can differ from the earlier build if
+that configuration changed. The deployed artifact includes
+`/.well-known/warmbly-release.json` and is retained as a workflow artifact.
+Subsequent releases publish the same built files to Pages and configured static
+asset targets. Static asset requests do not invoke a Worker script; confirm the
+account's current limits and pricing before enabling any other Workers feature.
+
+Before moving a production hostname, verify the staging site's certificate,
+TLS policy, root and nested routes, assets, response headers and redirects.
+Archive its existing Pages association and DNS. If verification fails after a
+cutover, restore that association and DNS, or deploy the saved asset artifact to
+the same Worker name. Keep the Pages deployment and its configuration available
+through the rollback window. A source merge alone does not attach a domain.
+
### Whole-domain connects
A workspace can connect every mailbox on a [Google Workspace domain or Microsoft 365 organization](/guides/mailbox-import/#connect-a-whole-google-workspace-domain) through one administrator's grant (**Add account > Google > Whole Workspace domain**, **Add account > Microsoft > Whole organization**). These are read by the backend only: it mints every token for those mailboxes itself and hands them to workers per use, so workers need nothing here. The complete setup, step by step, is in [whole-domain mailbox connects](/development/whole-domain-connect/).