Repository navigation
Deploy PR previews with HarperFast/deploy-action - #797
dawsontoth wants to merge 5 commits into
Conversation
Replace the hand-written pr-preview.yaml with preview.yaml, the action's two-job preview workflow (deploy in `preview`, cleanup in `preview-cleanup`). It authenticates by OIDC only, so the stored username and password are no longer read, and it never checks out PR code; fork PRs get no preview. The site needs a Docusaurus build, which must not run with the preview identity. preview-build.yaml builds each PR's head commit in an unprivileged pull_request run and uploads it; the deploy job waits for that run, downloads the artifact under a config.yaml of its own, and deploys it as a payload preview at the root of its own host. The local preview script follows the build workflow's name and base URL. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
There was a problem hiding this comment.
Code Review
This pull request updates scripts/preview-pr.mjs to query the "Build PR Preview" workflow instead of "Deploy PR Preview" and sets the DOCUSAURUS_BASE_URL to / instead of a PR-specific path. Feedback points out that using the --paginate flag with gh api and --jq can result in multiple JSON documents being returned, which will cause a SyntaxError when parsed. It is recommended to remove the --paginate flag.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
main dropped reference/** from the preview paths and added scripts/assemble-content.mjs, and gave the build a token for the assembler's GitHub calls. Both now apply to preview-build.yaml and preview.yaml in place of the deleted pr-preview.yaml. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`--paginate` with `--jq` printed one document per page, which
JSON.parse refuses once a branch has more than one page of runs. The
workflow's runs endpoint, filtered to successful runs of the branch,
returns the newest one first, and `{}` when there is none.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
kriszyp
left a comment
There was a problem hiding this comment.
I know it is in draft, but I still approve :).
🤖 Reviewed with Muse Wonder 1.0 · adjudicated by Codex
The deploy job took any run of the build workflow at the PR's head commit from this repository, so a second PR at the same commit could be picked, and its artifact is named for that PR. Only a run from this PR's branch counts now; a branch has one open PR into main at a time. `npm run preview:pr` took the newest successful run of the PR's branch, which can belong to a later PR that reused the branch name. It now takes the newest one at one of this PR's commits. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
well, mostly works -- there may be an issue with how Harper starts up the preview deployments received through replication, so the west node isn't running the preview properly. I have a session investigating that now. But that's a core issue, most likely. |
⊙ Problem
pr-preview.yamlchecks out each PR's code underpull_request_target(fork PRs too, after an approval inpreview), builds it in a job that holdsHARPER_PREVIEW_USERNAMEandHARPER_PREVIEW_PASSWORD, and deploys apr-<N>component that stays until the PR closes. Previews pile up on the preview host (#695).HarperFast/deploy-actionnow does per-PR previews on Harper 5.4 with OIDC only, and Kris suggested running it here so it's exercised on real PRs (HarperFast/deploy-action#1).💡 Solution
preview.yamlis the action's example workflow: adeployjob in thepreviewenvironment and acleanupjob inpreview-cleanup, each with the fork guard. No checkout, no stored credential, and the action keeps one PR comment and a GitHub Deployment. Previews move from<preview host>/pr-<N>tohttps://<branch>.app.<cluster domain>/and expire on their own (7 days by default).preview-build.yamlbuilds the site. The action's default deploys a PR's commit by reference, but this repo has no Harperconfig.yamland the cluster doesn't run a Docusaurus build. So, as the action's README and the CI guide describe for apps that need a build, an unprivilegedpull_requestrun builds the PR's head commit and uploadspr-<N>-build. The deploy job waits for that run, downloads the artifact intosite/build, writes its ownsite/config.yaml(the same static config production uses), and deployssiteas a payload withby_ref: false.scripts/preview-pr.mjs(npm run preview:pr) looks for the new build workflow's runs, and serves with base URL/.The action is pinned to
v1.0.0by its commit,45fa59b.🤔 Things to look at
pull_request_target, soworkflow_runcan't deploy. The deploy job polls for the build of its exact commit, from a branch of this repository. It deploys nothing if the PR moves on or closes, and fails if the build fails, takes over 30 minutes, or never starts.pull_requestrun for it, so the deploy job fails after 10 minutes and says why. Assemble the v5 reference and open release notes from harper and harper-pro #788 is in that state now. The old workflow built conflicting PRs anyway.npm run preview:pr, subject to the repository's fork-approval setting.docs-site, production's component name, so previews aredocs-site-pr-<N>. Each gets its own database branch (the default). The site has no tables.actions: readon the deploy job, beyond the example, is for reading the build's runs and downloading its artifact.📋 Enabling previews (Dawson, @Ethan-Arrowood)
This PR changes no cluster or repository settings itself; these are done by hand, and the checked ones were done on November 5 and 6. A real preview needs this PR merged, since
pull_request_targetrunsmain's workflow and the trust policies pinmain.Before merging
Steps 3a, 3b and 4 don't depend on the cluster, so they can happen in any order.
preview.harper-documentation.harperfabric.com(org-jekmjscs93exkury/clu-ifppwn095xb3s5ze). Dawson upgraded it in Fabric to 5.4.0-beta.2 on November 5, when it had one instance, and the open PRs' existing previews served again within a minute.alpha.1has noenable_previewsorharper preview setup. It now also has aus-west1-a-1node, and Dawson upgraded it to 5.4.1 on November 17, which starts a preview on every node (see Verification).*.app.preview.harper-documentation.harperfabric.com. Fabric's host-manager adds that wildcard when it renews a certificate, which it does once fewer than 40 days remain (here from November 9); upgrading doesn't renew it. To renew it sooner, Dawson createdletsencrypt/wildcard-owedin the instance's folder onhm-us-central1-aon November 5, and host-manager's daily run renewed it at 12:17 UTC on November 6 (until Feb 4), withDNS:*.app.preview.harper-documentation.harperfabric.com. The old/pr-<N>previews still serve. A host under*.app.gets a route only once a deployed preview publishes it, so until then a connection to one is reset. To check the certificate:harper preview setup app=docs-site, signed in as asuper_user, from a checkout of this branch (setup reads.github/workflows/preview.yamland checks it).loginprompts for the target,https://preview.harper-documentation.harperfabric.com:9925/.docs-site-ci-previewrole and user and both trust policies, and enables previews fordocs-site. It also sets theHARPER_PREVIEW_TARGETrepository variable, which is separate from today's secret of the same name. Dawson ran it on November 5: it created the role, the user, and thegithub-actions-docs-site-previewandgithub-actions-docs-site-preview-cleanuptrust policies, and set the variable tohttps://preview.harper-documentation.harperfabric.com:9925/.previewenvironment: allow onlymainunder Deployment branches and tags. Keep itsdevelopersreviewers until this merges:main's oldpr-preview.yamlbuilds fork PRs with the stored password, and those reviewers are what gate it.preview-cleanupenvironment: create it, with no reviewers and the samemainrule.pull_request_targetfor.github/workflows/preview.yaml: "Allow Harper previews", created November 5. The repository is public, and GitHub blocks the event from December 2, with brownouts on November 9 and 16. From the action's README:After merging
previewenvironment: remove thedevelopersreviewers, or every docs PR's preview waits for an approval.HARPER_PREVIEW_USERNAME,HARPER_PREVIEW_PASSWORDandHARPER_PREVIEW_TARGETsecrets, and thePREVIEW_CLEANUP_APP_IDvariable andPREVIEW_CLEANUP_APP_PRIVATE_KEYsecret if they're set. Nothing reads them now.pr-<N>environments.pr-<N>component from the preview cluster, open PRs' included. Once this merges, nothing drops one when its PR closes: the old workflow's cleanup goes with it, and the preview identity reaches onlydocs-site-pr-*. An open PR gets a new preview on its next push that changes the docs. Signed in as for step 2, once per component:Outside this PR
companion-check.yaml, allowingpull_request_target,scheduleandworkflow_dispatch: "Companion Check", created November 13. It also runs onpull_request_target, so without a policy it fails during the brownouts and stops on December 2.✅ Verification
checkPreviewWorkflowFile(whatharper preview setupruns, the same inmainandv5.4.0-beta.2) finds no problems, nothing unverified, and nothing unsafe inpreview.yaml. Adding a PR-head checkout, or dropping the fork guard, gets refused.validate.yamlin place of the build workflow:run-id.pull_requestrun at all.npm run preview:pr's lookup, run withvalidate.yamlin place of the build workflow: finds the newest successful run of a branch, and{}for a branch with none.main: Harper's check again finds nothing inpreview.yaml, and its paths matchdeploy-fabric.yaml's.npm run test:workflowspass. actionlint isn't installed here and wasn't run.*.app.preview.harper-documentation.harperfabric.com, and the open PRs' old/pr-<N>previews serving 200.harper preview deploy app=docs-site pr=797 …with asuper_userlogin, from this branch's build beside the deploy job'sconfig.yaml. It servedhttps://ci-preview-deploy-action.app.preview.harper-documentation.harperfabric.com/fromus-central1-a-1with a valid certificate, and sampled pages answer as production's do. The cluster's newus-west1-a-1node had the wildcard certificate but reset the preview host's connection, while still serving the old/pr-<N>previews: a Harper bug, where a node that receives a replicated deploy never starts the new isolated application. HarperFast/harper#4407 fixed it in 5.4.1.harper preview dropstopped both nodes serving the preview host, while the old/pr-<N>previews kept serving. Deploying it again (b9c77551) served it from both nodes, with a valid certificate and the same pages, andus-west1-a-1reported itcertifiedrather thanuncertified.Relates to #695.
🤖 Generated with Claude Code