Skip to content

What deploys how ​

Since #1102, merging to main deploys everything by itself once CI passes. You only step in to switch it off, run a part by hand, or handle Terraform changes.

On every merge to main ​

WhatDeployed byWhenNotes
Platform site (platform.lovely-home.co.uk)Cloudflare Pages Git integration and Deploy on merge when platform code changesEvery push to main; also bash scripts/deploy-platform-admin.sh after CI when functions/api/platform/**, functions/api/public/**, functions/api/stripe/**, or platform-admin/** (etc.) changedBuilds npm run build:platform (prepare-platform-pages-functions.mjs stages platform Functions). Env var changes need Terraform or a manual redeploy (see platform-admin.md).
Marketing site (lovely-home.co.uk)Deploy on merge → scripts/deploy-lovely-home-website.shwebsite/** (or that script and its helpers) changedwebsite/ plus the language pages, staged in dist-marketing-production/ with site.css, account.css, site.js and pricing.js minified (#1412). The lovely-home Pages project has no Git integration, so nothing else deploys it (#1132). Afterwards it checks that lovely-home.co.uk serves the merged commit, and fails if it doesn't. It deploys from inside the staged folder, so no Functions ship with it (#1199).
hub-jobs Worker (prod lovely-home-hub-jobs + sandbox lovely-home-hub-jobs-sandbox)Deploy on merge → scripts/deploy-hub-jobs-worker-code.mjsworkers/hub-jobs/** changedCode-only update. Queues, secrets, vars and the cron stay as Terraform set them.
Public orchestrator workflows (lovely-hub-provision: CI, CD, provision, regression, cleanup, alerts)Deploy on merge → sync-all-public-orchestrator-workflows.mjs + sync-public-workflow-alerts.mjsA docs/public-repo-workflow-template*.yml or a sync script changedNeeds the repo secret PUBLIC_WORKFLOWS_SYNC_TOKEN (below).
Hub API Workers (every home in worker/package.json)Deploy on merge → D1 migrations, then deploy-all-workers.mjs --skip-e2eworker/** changed, apart from tests, docs, and wrangler.toml / package.json registry editsSame as npm run d1:migrate:all + npm run deploy:all in worker/. Regression e2e-* hubs are skipped.
Hub Pages (each home's app)Deploy on merge → Hub CD dispatch on the public repo, all sitessrc/, public/, hub functions/, index.html, Vite config or package-lock.json changed (a package.json script edit alone doesn't redeploy every home)Runs after the hub Workers when both changed, so new pages never call an old API.

Deploy on merge runs on each release commit (Release x.y.z (#N)), which Release on merge pushes right after a PR merges; the PR merge itself deploys nothing (#1550, see releases.md). It waits for the test and Hub smoke (demo) statuses on the release commit. If CI fails, nothing deploys. It posts one message to Slack #workflows. Registry commits (platform: record/drop …) and docs-only merges deploy nothing new.

A failed deploy is retried by the next merge (#1190) ​

Every part ends each merge with a Deploy: … commit status on the merge commit: Deploy: hub-jobs Worker, Deploy: Public workflows, Deploy: Hub API Workers, Deploy: Hub Pages, Deploy: Marketing site and Deploy: Platform site. Success means the part is live at that commit, either because it deployed or because nothing it ships had changed.

Plan looks back along main (up to 100 commits) for each part's newest success, and deploys the part when anything it ships changed since then. So a deploy that failed, was cancelled, or was replaced while it queued stays pending, and the next merge deploys it even if that merge didn't touch the part's files. The plan summary shows each part's base commit.

  • A part with no success in the last 100 commits counts as unknown and deploys. The first merge after this change deploys every part once for that reason, and so does the first merge after a long outage.
  • When a merge gets no CI (docs only) but a part's pending changes include code, that part is held with an error status: deploying it would ship code no CI passed on. The next merge CI tests deploys it.
  • A merge that lands while a deploy is still running deploys that part again on its commit, since the running one hasn't succeeded yet. The public orchestrator queues it behind the running one.
  • With DEPLOY_ON_MERGE off (or plumbing), the parts it switches off get no status, so their changes deploy when it's switched back on.

Where the deploys run (#1227) ​

Deploy on merge hands the hub-jobs Worker, hub API Workers, Hub Pages and the marketing site to Hub deploy dispatch on the public orchestrator (lovely-hub-provision), which runs them on GitHub's free runners. The VPS only plans and hands over, so a deploy no longer queues behind other jobs on the single lovely-home runner. The public run:

  • waits for CI on the merge commit (polling there is free);
  • runs each hub's D1 migrations and then its Worker, up to 6 hubs at a time, then Hub Pages;
  • shows each part on the merge commit as a commit status (Deploy: Hub API Workers, Deploy: Hub Pages, Deploy: hub-jobs Worker, Deploy: Marketing site), with a link to the run;
  • posts the Slack #workflows message. The VPS also posts one when it synced the public workflows or couldn't hand over.

Any GitHub account can read the public repo's logs, so every deploy there runs through scripts/run-quiet-deploy.mjs. The command's output goes to a file, and the log gets one line per deploy (for example ✓ Hub API Worker (demo): version 1a2b3c4d). The hub's hostnames, IDs and coordinates from wrangler.toml are masked. When a deploy fails, the log shows wrangler's error lines, and the full output goes to the private lovely-home-e2e-reports R2 bucket under deploy-logs/<run id>-{attempt}/. The failed commit status names that folder.

Repo variable DEPLOY_ON_MERGE_RUNNER:

ValueEffect
public (or unset)Hub deploy dispatch runs the deploys, as above.
vpsThe jobs in deploy-on-merge.yml run on the VPS as before (the fallback).

The public workflows sync always runs on the VPS: its token can rewrite the public repo's workflows, so it never goes there. When a merge changes both a public workflow template and something to deploy, the sync goes first, so the deploy runs the new template. Setup and troubleshooting: public-deploy-dispatch.md.

The rules live in scripts/lib/deploy-on-merge-plan.mjs, with tests in tests/deployOnMergePlan.test.js.

Switching it off ​

Repo variable DEPLOY_ON_MERGE (Settings → Secrets and variables → Actions → Variables):

ValueEffect
on (or unset)Everything above.
plumbingOnly hub-jobs and the public workflows. Hub Workers, Hub Pages and the marketing site wait for you.
offNothing.

Platform Pages still gets Git deploys on every main push; Deploy on merge also runs an explicit wrangler deploy when platform API or admin assets change so Functions cannot lag behind Git integration.

Static sites carry no Functions ​

wrangler pages deploy {folder} bundles ./functions from the working directory, not from the folder it deploys. The repo root's functions/ are the hub and platform Functions, and their Access middleware answers 503 on a project without Cloudflare Access. So the static sites (marketing, marketing-sandbox, the lovely-hub.com zone page) always deploy from inside their own folder (#1199). tests/staticPagesDeployFunctions.test.js checks this.

"Creating deployments too quickly" ​

Cloudflare limits how fast one account can create Pages deployments (code 8000072). Several hub builds at once, plus a platform redeploy, can hit it. The limit is not a plan setting, and only Cloudflare support can raise it. The hub upload (deploy-hub-pages-from-artifact.sh), the platform admin deploy and the platform-sandbox refresh all run wrangler pages deploy through scripts/lib/pages-deploy-retry.sh. That script waits 30, 60, 120 and then 180 s and deploys again, for this error only. Any other error still fails at once (#1526). PAGES_DEPLOY_RETRY_WAITS changes the waits.

Running a part by hand ​

Actions → Deploy on merge → Run workflow on main. Left blank, parts deploys whatever hasn't deployed since its last success (see above). Set it to any of hub_jobs, public_workflows, hub_workers, hub_pages, marketing or platform_pages to deploy those as well, whatever changed. It still waits for CI on that commit, and runs where DEPLOY_ON_MERGE_RUNNER says.

From a laptop: bash scripts/deploy-lovely-home-website.sh, npm run deploy:all --prefix worker, CD — Hub Pages in Actions, or node scripts/deploy-hub-jobs-worker-code.mjs.

Still manual ​

WhatHowWhen
Terraform (Pages project settings and env vars, Access apps, queues, D1, hub-jobs bindings and secrets)Platform admin Terraform in Actions for prod. Sandbox: local apply with backend.platform-sandbox.hcl (sandbox-hub-quickstart.md).When a PR changes terraform/**, or after rotating a secret in hub.tfvars. Code changes don't need it.
Sandbox marketing + platformEvery regression run deploys its checkout_ref first (#1110), and the nightly run deploys main. By hand: Deploy sandbox Lovely Home. platform-sandbox has no Git deploys (#1135): merges to main don't change it, so a run tests one commit throughout. New test homes update its site list on the same commit.Automatic with regression. Run it by hand only to look at a branch on sandbox without a regression.
Release taggit tag vX.Y.Z && git push origin vX.Y.Z → Release workflowWhen you cut a release.
VPS (Grafana, runner)git pull + docker compose … up -d --force-recreate on the VPSAfter ops/grafana/** changes.

One-off setup ​

PUBLIC_WORKFLOWS_SYNC_TOKEN (repo secret on home-dashboard): a fine-grained personal access token with access to marklovely/lovely-hub-provision only. It needs these permissions:

  • Contents: Read and write
  • Workflows: Read and write
  • Metadata: Read (added automatically)

Without it, the Public workflows job fails with a note and everything else still deploys.

The existing CLOUDFLARE_API_TOKEN secret is used for hub-jobs, the hub Workers and the D1 migrations. It already has Workers Scripts and D1 edit, because Terraform uses the same token for both.

Hub deploy dispatch needs no new secrets. On lovely-hub-provision it uses CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID, HOME_DASHBOARD_REPO, HOME_DASHBOARD_DISPATCH_TOKEN (Contents read and Commit statuses read and write on home-dashboard, as hosted CI already needs) and SLACK_WORKFLOWS_WEBHOOK_URL. On home-dashboard it uses PUBLIC_CI_DISPATCH_TOKEN.