[dawsontoth]

⊙ Problem

Harper 5.4 ships per-PR preview deployments (harper#3042): one setup command and one workflow file give every pull request its own isolated, branched preview on the customer's own cluster, with no stored secret. None of it is documented. The CI guide still teaches the hand-built 5.3 recipe from #715, with a role that can deploy any component, a custom domain per preview on Fabric, and per-node cleanup.

💡 Solution

• The CI guide leads with the 5.4 flow, on HarperFast/deploy-action: the preview workflow that runs the action, harper preview setup, the setup options and their matching action inputs, the preview and preview-cleanup environments, HARPER_PREVIEW_TARGET, and allowing pull_request_target in a public repository. Then the CLI-only starter workflow setup writes (collapsed), managing previews, an optional sweep workflow, private repositories, apps that need a build, the security model from the epic, and shared versus branched data. Path A gets a tip to deploy with the action on a 5.4 cluster. The 5.3 recipe becomes a short note linking to this guide at 62139d54.
• Studio's Previews panel gets one "Coming soon" note, with no version, so one edit updates it when it ships.
• Reference for everything 5.4 added: enable_previews, disable_previews and get_preview_policy; preview metadata, expiry and the cap on deploy_component; payload deploys setting host, urlPath, isolated and branchedDatabases; the dotted-project-name 400; ifDeploymentId; the component_deploy role grant; deployment.previews.*; harper preview setup|teardown|deploy|drop|list; pattern credential grants; CORS wildcard origins; the shared port's 503 for an isolated host; fastifyRoutes under a host; bare globals reaching a branch; and the OIDC exchange refusing conflicting policies.
• 5.4 release notes: a "Pull Request Previews" section, and an upgrade note to check list_oidc_trust for conflicting pairs and upgrade every node.

🤔 Release notes here, not in #788

#788 (draft) moves the v5 reference and the 5.4 notes into harper's docs/, as one fragment per change, and its cutover ports the open docs PRs after it merges. Until then they live here, so this PR edits reference/ and release-notes/v5-lincoln/5.4.md like the other open 5.4 docs PRs. Each new 5.4 note is its own ### section, so it lifts into a fragment unchanged.

🤔 GitHub's pull_request_target date is December 2, not November 2

The epic and #715 say GitHub blocks pull_request_target in public repositories from 2026-11-02. GitHub moved it to 2026-12-02, with brownouts on November 9 and 16. The guide says December 2 and names the brownouts.

🤔 No per-component stagingRetention key exists

The brief listed a per-component stagingRetention; harper has none. What #3505 added is deployment.previews.stagingRetention.maxCount, which a preview's component uses in place of deployment.stagingRetention.maxCount. That is what's documented.

🔧 Changes

• learn/developers/deploying-from-ci.mdx: the "Per-PR previews" section replaces "Per-PR previews with shared databases"; two inbound anchors updated.
• reference/operations-api/operations.md: the "PR Previews" section (the three operations, the grant they write, the disable_previews barrier and its errors); deploy_component's isolated, branchedDatabases and preview parameters, payload routing, the project-name rule, and "Preview deployments" (expiry, cap, retention); the deployment record's preview and grant-filtered reads; how exchange_oidc_token treats several matching policies; list_oidc_trust's exchangeable and conflict invalid_reason; pattern grant_secret.
• reference/users-and-roles/overview.md: "Component Deploy Grants", and the preview operations among those an operations list cannot grant.
• reference/cli/commands.md: harper preview and its five actions, what setup checks in the workflow, payload routing parameters on harper deploy, pattern project for setup=true, and the rival-policy refusal in GitHub Actions setup.
• reference/configuration/options.md: deployment.previews.maxPerApplication, sweepInterval and stagingRetention.maxCount; CORS wildcard pointers.
• reference/components/applications.md: payload deploys setting routing, the shared port's 503, Fabric preview hosts, bare globals and branches, deploy_component's new fields, drop_component's ifDeploymentId, and get_components' preview.
• reference/http/configuration.md, reference/http/overview.md, reference/security/secrets.md, reference/components/javascript-environment.md, reference/components/module-loading.md, learn/developers/multiple-applications.mdx: CORS wildcard origins, fastifyRoutes in an isolated application, pattern grants, and the bare-globals change.
• release-notes/v5-lincoln/5.4.md: the upgrade note and "Pull Request Previews".

Fabric's preview hosts are already documented (#718), so the guide and reference link to Preview Hosts. Starting and stopping one isolated application and per-node drop results stay with #750, and isolated admission order with #759.

🤔 The guide assumes HarperFast/deploy-action@v1 is released

Asked for on this PR: the preview recipe now runs the action (HarperFast/deploy-action#1, open, untagged), not the CLI-only starter workflow that harper preview setup writes, which stays in a collapsed block. The Depends-on marker holds this PR until the action merges; tag v1 before this merges too, since every snippet uses @v1. The action's README is linked for the full input list rather than copied.

Which harper PR each part documents

All three are now merged to harper main (#3807 as 76797710, #3811 as 79aec74f, #3812 as 24574d0b), and the docs were rechecked against them. Everything else documents harper#3505, harper#3617, harper#3809, and the branch-removal retries harper#3600, harper#3763 and harper#3818, which change nothing a reader does.

Part of this PR	Depends on
CLI "What setup checks in the workflow" (head through env or VAR=, steps with any input, the cleanup note); get_preview_policy's operations problem; the reachability gateway wording; disable_previews listing again when a drop removed nothing	harper#3807
exchange_oidc_token "When several policies match"; list_oidc_trust's exchangeable and conflict invalid_reason; the rival refusal in harper deploy setup and enable_previews; the 5.4 upgrade note and "Conflicting Trust Policies Are Refused"	harper#3811
disable_previews fencing every node, the 403 for a fenced activation, the generation constraint, fence_preview_releases, and the release note's barrier paragraph	harper#3812

✅ Verification

• npm run format:check and npm run build pass, with no broken links or anchors.
• Every parameter, default, status and message checked against harper origin/main at 79aec74f, which has all of #3505, #3617, #3807, #3809, #3811 and #3812. The merged #3811 compares operation scopes with permission groups expanded and names a same-audience rival first, and the merged #3807 refuses only a head the workflow shows outright; both are reflected.
• Against a scratch [email protected] (scratch HOME and root): enable_previews refuses a localhost audience without hostSuffix, creates the four records, answers "already enabled" on a rerun and 409 on a different maxPreviews; get_preview_policy's fields; deploy_component project=shop.pr-12 answers 400; harper preview deploy branch=fix/Cart serves fix-cart.<domain> and records preview on the deployment; harper preview list; disable_previews drops both previews and removes the identity, and a second call answers "not enabled".
• Not run here: setup's GitHub side, a real OIDC run, and routing to an isolated preview.
• Version badges are v5.4.0: #3505 is in v5.4.0-alpha.1, #3617 in v5.4.0-alpha.2, #3809 and the rest are on main after it, and v5.3.5 has no utility/previewIdentity.ts.

Depends-on: HarperFast/harper#3807, HarperFast/harper#3811, HarperFast/harper#3812, HarperFast/deploy-action#1

🤖 Generated with Claude Code

Related PRs: #788 overlaps (moves reference/ and the 5.4 notes to harper; ported at its cutover), #750 overlaps (merged; its edits to the 5.3 recipe stay in the linked 5.3 version, and its drop reference is kept), #759 independent (linked, not re-documented), 18 others independent (other 5.4 docs PRs editing different sections of the same files)
Complexity: medium

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-790

This preview will update automatically when you push new commits.

[gemini-code-assist]

Code Review

This pull request updates the documentation to cover new features in Harper v5.4.0, such as Pull Request Previews, Component Deploy Grants, payload deployment options, and OIDC trust policy updates. The review feedback consistently points out violations of the repository's style guide regarding the mid-sentence use of the <VersionBadge> component in prose, providing actionable suggestions to replace them with plain text in the format (Added in: vX.Y.Z) or (Changed in: vX.Y.Z).

[kriszyp]

_{🤖 Reviewed with Muse}

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-790

This preview will update automatically when you push new commits.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-790

This preview will update automatically when you push new commits.

[Ethan-Arrowood]

LGTM and claude! Feel free to merge this as soon as deploy-action#1 merges and v1 is tagged

[github-actions]

🧹 Preview Cleanup

The preview deployment for this PR has been removed.