Skip to content

ci(previews): deploy a live Studio preview for each PR - #2054

Merged
dawsontoth merged 11 commits into
stagefrom
claude/studio-pr-previews
Nov 17, 2026
Merged

dawsontoth merged 11 commits into
stagefrom
claude/studio-pr-previews

Conversation

@dawsontoth

@dawsontoth dawsontoth commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor
A fox painter hoists a fresh canvas into its own treehouse for each acorn letter a friend posts, while an owl lowers an empty frame from a treehouse whose letter was torn up

⊙ Problem

A Studio PR has no running build to try: reviewers check out the branch, or wait for dev. Harper 5.4 hosts a preview per PR (HarperFast/harper#3042), and Harper's own repos should dogfood it with HarperFast/deploy-action, as HarperFast/documentation#797 does for the docs site.

Closes HarperFast/central-manager#912.

🤔 Previews live on the central manager's own cluster

That is Dawson's plan: only the hdbms front end gets previews, at https://<branch>.app.dev.studio.harperfabric.com/, and they call the one dev CM. Each preview is a worker thread in CM's Harper process, not a sandbox, and the CM answers CORS only for origins it lists.

💡 Solution

🤔 Static files only, not the deploy template

The template is a fastify route plus @fastify/static: server code the PR controls. On CM's cluster that code could read CM's deployed .env (its AWS keys) and reach the cluster's CA through server.operation, so the preview runs none; preview.yaml writes the config. The cost: template changes aren't previewed, and previews lack the template's frame guard and cache headers.

🤔 Trusted users, shared data

A preview's JavaScript runs with its visitor's dev CM session, so the HARPER_PREVIEW_AUTHORS variable lists who gets one; unset, nobody does. Previews share data because branching forks every database but system, CM's included. Google and GitHub sign-in finish on the preview through the CM's one-time handoff code; an organization's SSO still lands on dev Studio.

🤔 Things to look at

The gate, polling, conflicts, permissions, and what isn't here
  • The gate reads the PR's author and the event's actor, so neither an unlisted user's push to a listed user's PR nor a listed user's push to an unlisted user's PR deploys anything. Cleanup checks only that a target is set, on its step rather than its job, because any other term in the job's if: makes harper preview setup unable to verify that cleanup runs on close. It skips the author list, so a preview goes when its PR closes even after its author leaves the list; dropping one that doesn't exist does nothing. With HARPER_PREVIEW_TARGET unset, neither workflow runs.
  • Polling. GitHub starts both workflows at once, and the trust policy matches only pull_request_target, so workflow_run can't deploy. The deploy job polls for the build of its exact commit, by a run title naming the PR. Only a run listed users started and triggered counts: any writer can make a run with that title from a PR into a base branch whose workflow they wrote. Unlike documentation#797, another PR's build of the same commit can't be picked, and a failed API call isn't read as "no build started". It deploys nothing if the PR moves on or closes, and fails if the build fails, takes over 30 minutes, or never starts; re-running it once a build succeeds deploys that build.
  • A PR with merge conflicts gets no preview: GitHub starts no pull_request run for it, so the deploy job fails after 10 minutes and says why.
  • Only PRs into stage get one. Both workflows filter on it, the default branch the trust policy pins; PRs into dev or prod run neither.
  • actions: read on the deploy job, beyond the example, reads the build's runs and downloads its artifact.
  • No sweep workflow. The cluster expires a preview 7 days after its last deploy, which covers a missed close. A sweep needs its own trust policy; add one if previews pile up.
  • Direct connections to clusters (Fabric Connect direct mode) probably fail from a preview, since those instances' CORS lists hold Fabric's own Studio origins. Not verified; proxied connections go through the CM.

⚖️ Alternatives

Four weighed
  • One job that builds and deploys: it would hold the preview identity while running the PR's install and build, and the trust policy accepts only pull_request_target.
  • A workflow_run deploy instead of polling: the trust policy pins event_name: pull_request_target, so that run could not exchange a token.
  • Required reviewers on preview instead of a list: every push would wait for an approval.
  • A deploy by reference: it would run the PR's own config.yaml, so a PR could load server code into CM's process.

📋 Before this merges (Dawson)

All eight done: this PR itself changes no cluster or repository settings.
  • Harper 5.4. The dev CM (dev-1-studio) runs harper-pro:5.4.1; previews need 5.4.0-alpha.2 or later.
  • Isolated workers. tls.unixDomainSockets: true is set beside http.securePort (9926), and Harper has restarted with its socket mirrors. threads.maxIsolated (default 8) caps live previews.
  • CORS. http.corsAccessList lists https://*.app.dev.studio.harperfabric.com, and a preflight from a preview origin passes with credentials.
  • Preview hosts reach their previews. *.app.dev.studio.harperfabric.com has DNS and a certificate, and a Symphony proxy publishes the CM's 443: it ends TLS and hands each connection to Harper's own sockets with PROXY v2, a preview host to its preview, so the CM still sees client IPs. central-manager's version play deploys it (HarperFast/central-manager#1224).
  • harper preview setup app=hdbms dataMode=shared target=https://dev.studio.harperfabric.com:9925 created the hdbms-ci-preview role and user and both trust policies (pinned to preview.yaml on stage, previews under .app.dev.studio.harperfabric.com, shared data), and set HARPER_PREVIEW_TARGET.
  • The HARPER_PREVIEW_AUTHORS repository variable lists the six GitHub logins that get previews. Edit it to change who does.
  • Environments preview and preview-cleanup exist, each allowing only stage, with no required reviewers: the list is the gate.
  • An Actions policy ("Allow Harper previews") allows pull_request_target for .github/workflows/preview.yaml, which GitHub blocks in public repositories from December 2.

🔧 Changes

✅ Verification

  • Harper's own check (Harper 5.4.0 and origin/main, branch stage): no problems, nothing unverified, nothing unsafe.
  • Sign-in on a preview: Google sign-in on the preview landed signed in there (Dawson, November 16).
  • Gate: vitest (727 files), tsc -b, oxlint, dprint, commitlint. Removing any new guard, in the workflow test or the sign-in code, turns a test red.
  • A hand deploy of this PR (hdbms-pr-2054) serves Studio through the CM's proxy. A deploy or cleanup by the workflow is not verified.
More checks
  • Harper's check refuses a PR-head checkout, a missing fork guard on either job, and branch main. A list term on the cleanup job's if: is reported unverified, hence the step gate.
  • The bundle (--mode dev, no VITE_TELEMETRY_ENABLED) calls dev.studio.harperfabric.com and holds no Datadog token, GTM loader or Reo script: 30 MB without sourcemaps.
  • The wait step, against verify-pr.yaml runs: fix(auth): verify email with the sign-up browser proof or the password #2050's head found its run and wrote run-id; a commit the PR had left, and merged feat(previews): turn on and manage PR previews from Studio #2045, exited 0 with a notice; another title matched nothing; a failing listing ran to the time limit.
  • The build selector, run with gh's jq against real verify-pr.yaml runs: a listed actor, in any case, selects the run; an unlisted one or an empty list selects nothing.
  • Sign-in tests cover splitting the code out of the fragment, the redeem request, CheckOAuth's order (clear, redeem, then the session check), and the redirect each button and getOAuthSignInUrl builds (Google, GitHub).
  • On GitHub: Verify PR's actionlint passed, and before the list gate this PR's own Build PR Preview #2054 run uploaded pr-2054-build (12 MB).
Review findings left open
  • cleanup shares neither the deploy's concurrency group nor its by_ref. deploy-action re-reads the PR after deploying and drops its own preview if the PR closed (preview.ts), drops by app and PR number only (dropClosedPreview), and its README says to keep cleanup out of the deploy's group.
  • A listed user can still get their own build into another listed PR's preview, through a run with that PR's title from a PR into another base branch. They could already change that preview by pushing to its branch; this way leaves no commit there.

🤖 Generated with Claude Code

Related PRs: 2 independent
Complexity: medium

Accepted behavior

Behavior the owner ruled intended, so there is nothing to file.

6 minor or nit
  • 6553d6e7dab2178e none maintainability — .github/workflows/preview.yaml — cleanup omits by_ref: false that deploy passes — accepted: dawsontoth (PR owner) ruled it intended in the authoring session for studio#2054, 2026-11-17
  • ce41e45cbb2d33c6 none concurrency — .github/workflows/preview.yaml — no supersession recheck between completed-build detection and deploy — accepted: dawsontoth (PR owner) ruled it intended in the authoring session for studio#2054, 2026-11-17
  • e4afb982f7aa04b1 none maintainability — .github/workflows/preview-build.yaml — added comments narrate YAML or restate helpers — accepted: dawsontoth (PR owner) ruled it intended in the authoring session for studio#2054, 2026-11-17
  • 98cb696214452d11 none security — src/features/auth/CheckOAuth.tsx — preview redeems unsolicited oauth_handoff codes (login CSRF) — accepted: dawsontoth (PR owner) ruled it intended in the authoring session for studio#2054, 2026-11-17
  • 4340790679e977a6 none reliability — src/features/auth/components/GoogleAuthenticationButton.tsx — absolute OAuth redirect assumes CM oauth =2.11 — accepted: dawsontoth (PR owner) ruled it intended in the authoring session for studio#2054, 2026-11-17
  • 20999181cb5401ef none concurrency — .github/workflows/preview.yaml — cleanup not serialized with in-flight deploy — accepted: dawsontoth (PR owner) ruled it intended in the authoring session for studio#2054, 2026-11-17

Ready-For-Promotion: 854693f urgency=normal late=folded

Review-Coverage: authored=claude; ran=cursor-composer,gemini,codex,cursor-grok; late=cursor-grok:adjudicated; adjudicated=domain; declined=muse; rounds=9; full=2 @ 854693f

Review-Attention: deep ~30m (sensitive: preview-build.yaml, preview.yaml +4; decisions: cleanup-ungated-by-author, artifact-consumer-allowlist, actor-allowlist-binding) @ 854693f

dawsontoth and others added 3 commits November 4, 2026 11:10
Each PR into stage from a branch of this repository gets a live Studio at
https://<branch>.app.<cluster domain>/, dropped when the PR closes.

preview-build.yaml builds the PR's head commit in dev mode, without
telemetry, in an unprivileged pull_request run and uploads web/.
preview.yaml (pull_request_target, from stage) waits for that build,
writes its own static config.yaml and deploys the payload as
hdbms-pr-<N> with HarperFast/deploy-action v1.0.0 over OIDC. Fork PRs
get no preview, and nothing in it checks out PR code.

workflowPrivilege.test.ts now checks that every pull_request_target job
has the fork guard and checks out nothing, since the cluster's trust
policy pins the file's path, not its content.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- The wait step also matches the build run's head branch, so another
  PR's run at the same commit is never picked.
- The guard test requires the fork guard as a top-level && term, with
  string literals stripped and no ||, so a negated, quoted or bypassed
  guard fails it.
- deploying.md says previews need the dev CM's CORS entry, sign in with
  email and password, and serve Harper's plain 404.
- Workflow comments keep only the constraints.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- preview-build.yaml names each run "Build PR Preview #<N>", and the
  wait step matches that title, so another PR's run of the same commit,
  even from the same branch, is never picked.
- A failed runs listing no longer counts as "no build started" after
  ten minutes; the 30-minute limit still applies.
- The fork-guard test refuses any condition with parentheses, braces or
  ||, so a guard inside a negated group or between two interpolations
  fails it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request adds documentation for PR previews in .github/deploying.md and introduces a test suite in src/lib/workflowPrivilege.test.ts to ensure that pull_request_target workflows are properly guarded and do not execute untrusted code. The feedback recommends enhancing the robustness of the tests by normalizing whitespace when verifying the fork guard condition and adding defensive checks to handle malformed workflow files without crashing.

Comment thread src/lib/workflowPrivilege.test.ts Resolved
Comment thread src/lib/workflowPrivilege.test.ts Resolved
Previews will live on the central manager's own cluster, where a
preview is a worker thread in CM's Harper process.

- Both workflows run only when a login in the HARPER_PREVIEW_AUTHORS
  repository variable (a JSON array) opened the PR and caused the
  event. Unset, nobody gets a preview: its JavaScript runs with the
  visitor's dev CM session.
- The deploy passes branched_databases: false. Branching would fork
  every database on the node but system, CM's included; the payload
  runs no server code, so sharing touches nothing.
- The fork-guard test splits the condition at parenthesis depth 0, so
  a function call such as contains(fromJSON(...)) passes while a
  guard inside a call, a negated group or a top-level || still fails.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@github-actions

github-actions Bot commented Nov 4, 2026 •

Copy link
Copy Markdown

Coverage Report

Status Category Percentage Covered / Total
🔵 Lines 85.9% 23213 / 27023
🔵 Statements 85.7% 24638 / 28747
🔵 Functions 81.87% 6459 / 7889
🔵 Branches 81.43% 20286 / 24912
File Coverage
File Stmts Branches Functions Lines Uncovered Lines
Changed Files
src/features/auth/CheckOAuth.tsx 97.67% 66.66% 100% 97.61% 29
src/features/auth/redeemOAuthHandoff.ts 100% 100% 100% 100%
src/features/auth/components/GitHubAuthenticationButton.tsx 100% 100% 100% 100%
src/features/auth/components/GoogleAuthenticationButton.tsx 100% 100% 100% 100%
src/lib/urls/getOAuthSignInUrl.ts 100% 85.71% 100% 100%
src/lib/urls/oauthHandoff.ts 94.44% 88.88% 100% 94.44% 30
Generated in workflow #2605 for commit 854693f by the Vitest Coverage Report Action

dawsontoth and others added 2 commits November 4, 2026 12:00
…shared

- The cleanup step runs only when HARPER_PREVIEW_TARGET is set and the
  PR's author is listed, so an unset variable doesn't fail every merge.
  The gate sits on the step: any other term in the job's if: makes
  harper preview setup unable to verify that cleanup runs on close.
- The setup command in the header and deploying.md now says
  dataMode=shared, which branched_databases: false needs.
- The fork-guard test also refuses index expressions.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…est can't read

The fork-guard check now compares with whitespace collapsed, so a guard
split across lines still counts. A jobs, job, steps or step value of the
wrong type is reported as a problem rather than crashing the test or
being skipped, so it fails instead of passing unchecked.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@dawsontoth
dawsontoth marked this pull request as ready for review November 9, 2026 17:05
@dawsontoth
dawsontoth requested a review from a team as a code owner November 9, 2026 17:05
@dawsontoth
dawsontoth marked this pull request as draft November 9, 2026 20:58
…views

# Conflicts:
#	src/lib/workflowPrivilege.test.ts
dawsontoth and others added 3 commits November 16, 2026 11:39
…igin

The sign-in buttons now name the serving origin in the OAuth redirect. The
central manager keeps only the path for an origin it does not list, so dev
Studio and production behave as before. For an origin in its
postLoginRedirectOrigins (Studio PR previews on dev), it hands the sign-in
over with a single-use oauth_handoff code in the fragment. /#/check-oauth
clears that code from the URL and redeems it at POST /oauth/handoff from the
page itself, since Harper names the session cookie after the request's
Origin, then checks for the session as before.

Refs HarperFast/central-manager#911.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Any repository writer could make a run of their own preview-build.yaml with
another PR's run title and commit, from a PR into a different base branch,
and the wait step would pick it as that PR's build. The step now counts a run
only when its actor and triggering actor are both in HARPER_PREVIEW_AUTHORS.
Also drops comments that restated the names they sat on.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…iables

actionlint failed Verify PR with SC2016 on the single-quoted jq expression.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@dawsontoth
dawsontoth marked this pull request as ready for review November 17, 2026 14:25

@kriszyp kriszyp left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 Reviewed with Codex

Comment thread src/lib/workflowPrivilege.test.ts Resolved
Comment thread .github/workflows/preview.yaml Resolved
Comment thread .github/workflows/preview.yaml Resolved
Comment thread .github/workflows/preview.yaml Resolved
…y closed PR

Kris's review of #2054:

- preview.yaml writes its static config.yaml before downloading the build,
  and the pull_request_target guard test now refuses any step after an
  artifact download except deploy-action, so no step can execute what the
  PR built. download-artifact keeps every file inside its path.
- Cleanup no longer checks the author list, so a preview is dropped when its
  PR closes even after its author leaves the list. Dropping a preview that
  doesn't exist does nothing.
- Both workflows skip when HARPER_PREVIEW_TARGET is unset, instead of
  building and waiting before deploy-action finds no target.
- The deploy job's failures say to re-run it once the build succeeds, and
  .github/deploying.md says so too.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@dawsontoth
dawsontoth added this pull request to the merge queue Nov 17, 2026
Merged via the queue into stage with commit f0c1172 Nov 17, 2026
8 checks passed
@dawsontoth
dawsontoth deleted the claude/studio-pr-previews branch November 17, 2026 19:02
@dawsontoth
dawsontoth deployed to preview-cleanup November 17, 2026 19:02 — with GitHub Actions Active

This branch was successfully deployed

1 active deployment
preview-cleanup — 854693fc Deployed Nov 17, 2026 by dawsontoth via cleanup #1
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants