[Epic] PR preview deployments #3042

Turn on pull-request previews for an application on a Fabric cluster, and every PR's build is served at its own subdomain, <branch-slug>.<app>.<cluster-domain>, with a valid certificate. Each push updates the preview, and closing the PR removes it. Customer setup should be one toggle in Studio plus one workflow file, with no stored secrets, DNS records or certificates to manage.

Example: a PR from branch david/1778-custom-regions is served at https://david-1778-custom-regions.<app>.<cluster-domain>.

This is the next step after staged component deploys (#2315), and the "preview deployments" item of the Ephemeral Instances roadmap lane, beside #641 and #642. Studio is the first consumer.

Where things stand

Previews already work by hand on 5.3.0. HarperFast/documentation#715 (stacked on HarperFast/documentation#713) documents a recipe, "Per-PR previews with shared databases":

• A pull_request_target workflow runs from the default branch and never checks out PR code.
• It deploys each PR's head commit with by_ref, as an isolated application my-app-pr-<n> at pr-<n>.<suffix>.
• Previews share the cluster's databases. On 5.3.0 and 5.3.1, no deploy path produces a database branch (A package deploy's branchedDatabases is ignored at load, so the application runs on its base databases #3071, deploy_component accepts branchedDatabases on a payload deploy and silently ignores it #3044).
• Cleanup calls every node directly, and checks that the component and its worker are gone.

It works, but it takes a lot of setup. This epic removes that cost one mechanism at a time:

What already exists

• Isolated applications: a dedicated worker per application, bound to one host (feat(threads): run an isolated application in a dedicated worker thread #2524). threads.maxIsolated caps them at 8 per node by default; a deploy past the cap answers 409.
• Scoped restarts: restart_service with scope: '<app>' restarts one isolated application's worker and nothing else (5.3.0).
• Branched databases: a per-application copy-on-write fork (Give an application a private, durable fork of a database #2352, feat(branches): declare tables into a branch through @table, ensureTable and defineTable #2523, feat(branches): remove an application's branched databases on drop_component #2517). Not yet reachable through a deploy (A package deploy's branchedDatabases is ignored at load, so the application runs on its base databases #3071, deploy_component accepts branchedDatabases on a payload deploy and silently ignores it #3044).
• OIDC trusted publishing: CI deploys with a GitHub Actions token instead of a stored credential (feat: OIDC trusted publishing — deploy from CI with no stored credential #2173, in 5.3.0). A policy can pin workflow_ref to the default branch's workflow and event_name: pull_request_target.
• Staged deploys: build aside, canary certification, provenance and deployment_id (Staged component deploys: land build-aside-then-swap as a sequence of small PRs #2315).
• Fabric routing: host-manager routes a host one label under a claimed *.domain to an isolated application's worker sockets, and serves a wildcard certificate for it (HarperFast/host-manager#224).

Shape

1. A preview is an isolated application named <component>-pr-<n>, with host: <branch-slug>.<label>.<cluster-domain>. Applications with tables add branchedDatabases once A package deploy's branchedDatabases is ignored at load, so the application runs on its base databases #3071 and deploy_component accepts branchedDatabases on a payload deploy and silently ignores it #3044 are fixed. Until then, previews share the cluster's databases, as the documented recipe does.
2. CI deploys it straight to the cluster, authenticated by OIDC, as an identity that can only deploy and drop that application's previews.
3. Central Manager acts once per application, when previews are enabled. It adds a wildcard DNS record, puts the wildcard on the instances' certificates, sends the claim host-manager routes on, and creates the trust policy and scoped role on the cluster.
4. Closing the PR drops the preview. An expiry and a per-application cap catch anything the close event missed.

The branch slug is one lowercase DNS label:

• Anything outside [a-z0-9] becomes -, and runs collapse.
• It is cut to 40 characters, with a hash suffix when cut.
• Reserved names fall back to pr-<n>.

For example, david/1778-custom-regions becomes david-1778-custom-regions. The documented recipe uses pr-<n>.<suffix>, which needs no slug at all.

Sub-issues

Harper core

• Payload deploys can set host, urlPath, isolated and branchedDatabases #3043
• deploy_component accepts branchedDatabases on a payload deploy and silently ignores it #3044
• Start and stop one isolated application without restarting the shared workers #3045
• Scope deploy permissions to component names #3046
• deploy_component deploys project=shop.pr-12 onto shop #3047
• Record preview metadata on a deployment, and expire previews #3048
• Per-component build retention, so previews keep fewer copies #3049
• Allow origin patterns in corsAccessList #3050
• Let an isolated application with a host use fastifyRoutes #3051
• Shared workers answer an isolated application's host while its worker is down #3052
• Bind the bare databases/tables globals to an isolated application's branches #3053
• Grant a deploy credential to a component-name pattern #3090
• Report per-node results from a replicated drop_component, and make dropping an absent component a no-op #3091
• A package deploy's branchedDatabases is ignored at load, so the application runs on its base databases #3071

CI tooling

• harper preview: deploy, drop and list PR previews from any CI #3054
• A reusable GitHub Action for Harper deploys, with a PR preview mode #3055

Central Manager

• HarperFast/central-manager#900
• HarperFast/central-manager#901
• HarperFast/central-manager#902
• HarperFast/central-manager#903
• HarperFast/central-manager#904
• HarperFast/central-manager#905
• HarperFast/central-manager#906
• HarperFast/central-manager#907

Studio as the first consumer

• HarperFast/central-manager#908
• HarperFast/central-manager#909
• HarperFast/central-manager#910
• HarperFast/central-manager#911
• HarperFast/central-manager#912

Host Manager

• HarperFast/host-manager#240
• HarperFast/host-manager#241
• HarperFast/host-manager#242
• HarperFast/host-manager#243

Security model

• The workflow is trusted, not the PR. The job runs on pull_request_target from the default branch and never checks out PR code. The trust policy pins workflow_ref to that branch's workflow file, event_name: pull_request_target, and an environment, so a PR can't change the privileged workflow. Fork PRs are skipped by the workflow's same-repository condition.
• The PR's code still runs on Harper, with the preview role's rights. Until Scope deploy permissions to component names #3046, that role can deploy and drop any component. So previews belong on a separate preview cluster, or behind required reviewers when they share a production cluster.
• Data is shared until branches work. A preview's writes, schema changes and roles apply to the cluster's databases.
• Public repositories: GitHub's default execution protection blocks pull_request_target for affected public repositories from 2026-11-02. The repository's Actions policy has to allow it for the preview workflow.

Related, tracked elsewhere

• Document isolated applications, branched databases, and per-PR CI previews documentation#715 and Deploying from CI: lead with OIDC, and correct the deploy reference where it disagrees with Harper documentation#713: the CI guide, and the reference for isolated applications and branched databases.
• Isolated applications are admitted when no SNI route can reach them (no host, or a host shared by urlPath) #2757: refuse unroutable isolated applications at admission.
• Token operation scope is not enforced on the REST/GraphQL resource path #2201: token operation scope is not enforced on REST/GraphQL, so the preview role should hold no table permissions.
• Branched databases: blob store sharing, allocator, and GC safety #644: branched-database blob sharing and GC safety.
• Failed deploy payloads are retained forever; add age/count expiry so retried rollouts stop consuming tenant storage quota #2681: failed-deploy payloads are kept forever.
• HarperFast/central-manager#845: wildcard custom domains.
• HarperFast/central-manager#887: multi-value ACME TXT, a prerequisite.
• HarperFast/central-manager#570: ephemeral environments. This epic is its lightweight tier.

Not in this epic

• Customer-owned preview domains, via _acme-challenge CNAME delegation.
• A GitHub App mode that needs no workflow file.
• Promoting a previewed build to production by deployment_id. Builds are bound to their component today.
• Static-only previews served from the shared workers.
• Stopping idle previews, and resetting a branch from its base.
• A cluster per PR (HarperFast/central-manager#570).