Repository navigation
feat(preview-workers): preview a pull request on a Cloudflare Worker (#145) - #298
Merged
Merged
Conversation
…ts/ (#145) deploy-cloudflare/write-config.js becomes scripts/write-wrangler-config.js, unchanged, so that preview-workers can share it without reaching into another action's directory. deploy-cloudflare and dc-wrangler-config now call it there. No caller references the file: a search of the QuantEcon org finds it only in this repository. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WT8bMaHSAzv2LkwwAaSboE
…145) A new action, a sibling of preview-cloudflare, as the maintainer decided on 2026-11-07. It uploads the built site as a new version of an existing Worker with `wrangler versions upload --preview-alias pr-<number>`, which never changes what the Worker serves in production, at https://pr-<number>-<worker-name>.<account-subdomain>.workers.dev, and comments on the pull request through scripts/preview-comment.cjs, which gets a `workers` provider with its own marker and heading. It has preview-cloudflare's trust gate (scripts/preview-decide.sh), dispatch-alias, placeholder and outputs, and deploy-cloudflare's naming rules for the Worker, the subdomain and the 63-character alias label. deploy-url is built from the inputs, as the placeholder's URL is, and set only when wrangler's `version-upload` record names the same alias URL: a different one (a wrong account-subdomain) or none (preview URLs off) fails the job, and no record at all warns and falls back. deployment-url is the record's version URL. The harness gets preview-workers-url (the deploy step against a stub wrangler and a recorded record), preview-workers-config (the pinned wrangler, 4.158.0, accepts the generated config and writes its record in a dry run), and preview-workers cases in preview-comment, preview-wiring and preview-cli-install. The gate lists the new lockfile and the shared writer. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WT8bMaHSAzv2LkwwAaSboE
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WT8bMaHSAzv2LkwwAaSboE
Contributor
There was a problem hiding this comment.
Note
Copilot was unable to complete this review at the selected tier due to model policy or plan restrictions.
🔵 Needs a closer look
The change depends on Wrangler’s live versions-upload behavior and Cloudflare Worker API/settings fields that can’t be fully validated offline, so confirmation via the planned canary run is needed before proceeding.
No open issues 🎉
1 file not reviewed
preview-workers/package-lock.json: Generated file
What changed in this PR
Adds a new preview-workers composite action to publish per–pull request previews on Cloudflare Workers via wrangler versions upload --preview-alias, reusing the existing preview decision, change detection, and PR comment infrastructure and sharing the Wrangler config writer with deploy-cloudflare.
Changes:
- Introduces
preview-workers(inputs/outputs, validation, Wrangler install, upload, and URL/record verification) with pinned Wrangler dependencies. - Moves the Wrangler config writer into
scripts/and updatesdeploy-cloudflareand CI harness coverage to use and validate it. - Extends preview comment tooling, fixtures, docs, templates, changelog, and Dependabot configuration to support and document Workers previews.
| File | Description |
|---|---|
| templates/ci.yml | Adds an inert, commented example block showing how to use preview-workers as an alternative preview workflow setup. |
| scripts/write-wrangler-config.js | Introduces a shared script for generating per-run Wrangler configuration for Worker uploads/deploys. |
| scripts/preview-decide.sh | Updates documentation comments to reflect preview-workers as an additional consumer of the decision logic. |
| scripts/preview-comment.cjs | Adds a workers provider to render Workers-specific preview comment headings, marker, and preview URL format. |
| scripts/generate-docs.py | Includes preview-workers in the documentation generation ordering and index output. |
| scripts/detect-changed-lectures.sh | Updates comments to note preview-workers as a caller of the lecture change-detection logic. |
| preview-workers/README.md | Adds the generated README entrypoint for the new preview-workers action documentation. |
| preview-workers/package.json | Defines the new action’s pinned Wrangler dependency set for reproducible CLI installs. |
| preview-workers/package-lock.json | Pins Wrangler and transitive dependencies for preview-workers to ensure deterministic installs in CI. |
| preview-workers/action.yml | Adds the new composite action implementing Workers preview uploads, URL construction/verification, and PR commenting. |
| docs/user/README.md | Updates the user docs index to list and link the new preview-workers action. |
| docs/user/getting-started.md | Mentions preview-workers as an additional preview option alongside existing preview actions. |
| docs/user/composition.md | Updates the composition guide to include preview-workers in the preview action lineup. |
| docs/user/actions/preview-workers.md | Adds full user documentation for setup, behavior, security, and troubleshooting of Workers previews. |
| docs/user/actions/deploy-cloudflare.md | Updates token guidance to align with per-Worker token creation instructions reused by the new action. |
| docs/dev/TESTING.md | Documents the added CI harness coverage for Workers preview URL/record and config validation. |
| docs/dev/PLAN.md | Updates planning notes to reflect the new action and associated project status changes. |
| docs/dev/ARCHITECTURE.md | Updates architecture documentation to include preview-workers and the shared config writer in scripts/. |
| deploy-cloudflare/write-config.js | Removes the old per-action config writer now replaced by the shared script under scripts/. |
| deploy-cloudflare/action.yml | Switches the deploy action to call the Wrangler config writer from its new shared location. |
| CHANGELOG.md | Adds an unreleased changelog entry noting the addition of the preview-workers action. |
| .github/workflows/test-actions.yml | Extends the CI harness with new jobs and wiring updates to validate Workers preview behavior and the moved config writer. |
| .github/fixtures/preview-comment/workers-pending.md | Adds a golden fixture for the Workers “building/pending” PR comment rendering. |
| .github/fixtures/preview-comment/workers-no-deployment-url.md | Adds a golden fixture for the Workers “ready” comment when no per-version deployment URL is available. |
| .github/fixtures/preview-comment/workers-lectures.md | Adds a golden fixture for the Workers “ready” comment including lecture links and deployment URL details. |
| .github/fixtures/preview-comment/test.cjs | Expands the preview comment test harness to cover the Workers provider, fixtures, lookup behavior, and input-check cases. |
| .github/dependabot.yml | Adds the /preview-workers directory to Dependabot’s npm update scope/grouping. |
Review effort: Balanced
…irst real upload (#145) preview-workers-url's stub wrangler appended a version-upload line built from wrangler's source. It now appends the line wrangler 4.158.0 wrote for the first real upload, to qe-preview-canary on the canary's pull request (run 42766349959), with this job's Worker, subdomain and alias in it: the same fields in the same order, bundle_size included, and its version ID. The cases' version URLs follow that ID. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WT8bMaHSAzv2LkwwAaSboE
mmcky
added a commit
to QuantEcon/test-actions-lecture-intro
that referenced
this pull request
Nov 10, 2026
…ere gh run watch's run id comes from (#87) * docs(gate): preview-workers is among what the gate does not cover; say where gh run watch's run id comes from Comments and docs only. QuantEcon/actions#298 added preview-workers after gate.yml was written, and it deploys to no Worker. The README's 'Running the gate' now says what QuantEcon/actions' CONTRIBUTING says (QuantEcon/actions#301). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WT8bMazsJ95KLpeAGcWbbp * docs(gate): one item per semicolon in the header's list; the fallback prints only the run id (Copilot's review) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WT8bMazsJ95KLpeAGcWbbp --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This was referenced Nov 10, 2026
Merged
Closed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
#145 asks for pull-request previews on Cloudflare Workers, the platform Cloudflare now puts static sites on, in place of Pages. On 2026-11-07 the maintainer decided the shape: a sibling action,
preview-workers, not aplatform:input onpreview-cloudflare. The agreed design is in the issue's comment of 2026-11-10. The canary has had a Worker on the org account since 2026-11-09,qe-preview-canary, with an account-owned token scoped to that one Worker.preview-workersrunswrangler versions upload --preview-alias pr-<number>, which uploads a new version of an existing Worker and points the alias at it. It never changes what the Worker serves in production. The preview is athttps://pr-<number>-<worker-name>.<account-subdomain>.workers.dev. Most of the action is calls to code already onmain:scripts/preview-decide.sh), change detection, and the comment and placeholder (scripts/preview-comment.cjs, which gets aworkersprovider);deploy-cloudflare's config writer, moved toscripts/;deploy-cloudflare's rules for the Worker's name, the subdomain and the 63-character alias label.What is new is the check against wrangler's record. The action builds
deploy-urlfrom its inputs, as the placeholder does. The pinned wrangler (4.158.0, as onmainsince #294) appends aversion-uploadrecord of each upload, naming the alias URL Cloudflare serves. When that URL differs, or is missing, the job fails rather than post a link that cannot load:deploy-url, anddeployment-urlfrom the record's version URL when it is of the expected form, else empty with a warningaccount-subdomainis wrong. The subdomain is one per account, so unlike #216's Pages addresses it cannot legitimately differversions uploaddoes not turn them ondeploy-urlunchecked, withdeployment-urlempty: #216's fallbackChanges
preview-workers/action.yml(new)preview-cloudflare's conditions. Inputs:cloudflare-api-token,cloudflare-account-idandbuild-dir, needed only for a deploy, so the placeholder's job holds no secret;worker-nameandaccount-subdomain, required;lectures-dir,dispatch-aliasandplaceholder. Outputs:preview-cloudflare's four. The input check runs on every event: the Worker's name and subdomain must be hostname labels, and adispatch-aliasmust fit in one with the name. For a deploy,pr-<number>must fit too, and the secrets andbuild-dirare needed. The install isnpm cifrom the lockfile intoRUNNER_TEMP, with nothing added toPATH. The upload writes the config, runsversions upload, prints and reads the record, and checks the URL as in the table abovepreview-workers/package.json,package-lock.json(new)main'spreview-cloudflarelockfile with the package renamedscripts/write-wrangler-config.jsdeploy-cloudflare/write-config.jsin a commit of its own, sogit log --followkeeps its history. Its arguments are unchanged. The generated file's comment line now reads "Generated by quantecon/actions for one run.", and the code comments name both callersdeploy-cloudflare/action.ymldc-*jobs passscripts/preview-comment.cjsworkersprovider:## ☁️ Cloudflare Workers Preview Ready!,## ⏳ Cloudflare Workers Preview Building…, the marker<!-- quantecon-preview:workers -->, andpreviewUrlhttps://<alias>-<site>.workers.devwith the site<worker>.<subdomain>scripts/preview-decide.sh,scripts/detect-changed-lectures.shpreview-workerschecks the 63-character rule itself.github/workflows/test-actions.ymlpreview-workers-urlandpreview-workers-config(below).preview-workerscases added topreview-comment,preview-wiringandpreview-cli-install.dc-wrangler-configuses the writer's new path. The gate'sMUST_RUNlists the new lockfile and the writer, and the two new jobs are inharness-summary'sneeds:besidepreview-cloudflare-url.github/fixtures/preview-comment/test.cjs,workers-*.md(new)GITHUB_OUTPUT. No earlier version rendered theworkers-*fixtures, so the shared script rendered them and I read them by eye. They differ from the Cloudflare ones only in heading and hostdocs/user/actions/preview-workers.md(new),preview-workers/README.md(new)docs/user/actions/deploy-cloudflare.mddocs/user/README.md,scripts/generate-docs.pypreview-workersinORDERafterpreview-cloudflare, and the generated index rowdocs/user/composition.md,docs/user/getting-started.mdtemplates/ci.ymlplaceholderanddeployjobs, beside the Pages ones. It is inert until someone uncomments it.github/dependabot.yml/preview-workersin the npm directoriesdocs/dev/ARCHITECTURE.md,docs/dev/TESTING.md,docs/dev/PLAN.mdpreview-*row; #145 out of PLAN's open issuesCHANGELOG.md### Addedunder[Unreleased], above #290's### Changed. 15 insertions, 0 deletions, and everything from## [0.17.0]down is byte-identical tomainThe harness
A pull request's harness has no Cloudflare secrets, so the jobs cover everything short of a real upload:
preview-workers-urlruns thedeploystep fromaction.ymlagainst a stub wrangler. The stub refuses any command line butversions upload --config <path> --preview-alias <alias> --message <msg>, and a config that does not name the Worker and the site's absolute path. It prints what wrangler prints and appends the case'sversion-uploadline. There are 13 cases:The recorded line is the one wrangler 4.158.0 wrote for the first real upload, on the canary (run 42766349959), with the harness's Worker, subdomain and alias in it.
preview-workers-configinstallspreview-workers' own lockfile, writes the config with the moved writer, and dry-runsversions upload --preview-alias pr-5withWRANGLER_OUTPUT_FILE_PATH. It asserts that there are no "Unexpected fields", and exactly oneversion-uploadrecord of version 1 naming the Worker: a dry run writes it, with no version or URLs. This is what a Dependabot bump of the lockfile meets. One that renamed or re-versioned the record would leave every caller on the warning.preview-commentcovers:preview-workersandpreview-cloudflarenever taking each other's comment, though their headings start the same way;dispatch-aliaswith a 34-character name, then a 35-character one, the subdomain's three accepted forms, and line breaks.preview-wiringhas three new steps:dispatch-aliasand a badplaceholdereach fail before any install;preview-workersadds nothing toPATH, so that check looks for npm's own link ofwrangler.Each new case fails on the code it guards against. A throwaway workflow on
scratch/145-red(run 42765623274, the branch since deleted) first ranpreview-commentandpreview-workers-urlon this branch's code, which passed. It then broke one thing at a time, and passed only if the covering job then failed:main'spreview-comment.cjs, with noworkersproviderpreview-comment: 6 cases, withPROVIDER is [workers], not one of: netlify, cloudflarepreview-comment: the 55-character name for a deploy, the same for the placeholder, and the 28 + 35dispatch-aliaspreview-workers-url:other-subdomain,other-aliasandalias-line-breakdeploy-urlbuilt without the Worker's namepreview-workers-url: every case that sets a URLversion-uploadlinepreview-workers-config's own checkWhat I checked, and how
The issue check was made against
0f4ee09, and its agreed version is the issue's comment of 2026-11-10. From it, and since:https://setup-check-qe-preview-canary.quantecon.workers.dev/answers 200, and an alias never uploaded answers 404. That 404 is what the placeholder's links give before a pull request's first deploy, which the pending comment's text already says.versions uploadwritesversion-upload, version 1, withversion_id,preview_urlandpreview_alias_url. The URLs are built from the API'spreview_url_suffix, and left out when the Worker's preview URLs are off. I ran the dry run locally on both versions.versions uploadwill not do: it refuses a Worker that does not exist, whatever the token can do. It applies no routes,workers_devorpreview_urls: onlywrangler deploydoes. And it never sends production traffic to the version.gh search code write-config.js --owner QuantEconfinds only this repository, andpreview-workersis not used anywhere yet.709572d: a pull request, a second push, a dispatch, and a wrong subdomain failing.Action harness: all checksis green on709572d(run 42767031661), with everydc-*job passing on the moved writer.python3 scripts/generate-docs.py --check --check-examples --actionlint …,actionlintwith shellcheck, andpython3 scripts/lint-shell.py, all clean. actionlint is 1.7.12, checked against its release's SHA-256, and shellcheck is 0.11.0;preview-comment(91 cases),preview-workers-url(13),preview-workers-configanddc-wrangler-config, run step by step.The canary run, before this merges
A throwaway workflow on a branch of the canary, pinned to this PR's head and not part of the PR, ran the first real uploads to the canary's own Worker,
qe-preview-canary. It has two jobs:All four legs passed at
709572d. The canary PR was #83, now closed with the results, and its branch deleted:0cc12c0deployed: 'true', anddeploy-urlexactlyhttps://pr-83-qe-preview-canary.quantecon.workers.dev, serving the run.deployment-urlhttps://8815c202-qe-preview-canary.quantecon.workers.dev, serving the run.changed-fileslistedlectures/about.md. The Worker's production URL still served its Hello World. Its one failure was the check's own, not the action's: Workers' static assets answer/about.htmlwith a 307 to/about, which a browser follows and the check'scurldid not. Its printed record is now the harness fixture's line (709572d)c2470a79), while run 1's version URL,8815c202-…, still served run 1's build. The lecture link ended at/about, on the same hostdispatch-canary-workers,deployed: 'true', no comment, and production untouchedaccount-subdomain: quantecon-wrongCloudflare serves this preview at [https://dispatch-canary-workers-qe-preview-canary.quantecon.workers.dev], not at …quantecon-wrong…,deployed: 'false'and nodeploy-urlAt v0.18.0's staged release, the same run against the tag. After the release, a
preview-workersstep joins the canary'sci.ymlbesidepreview-cloudflare, so later staged releases exercise it.What to watch after merge
preview-workers, anddeploy-cloudflarebehaves as before.preview-workers-configas well asdc-wrangler-config.setup-environment/,build-lectures/,containers/**or the lecture matrix.Not in this PR
The pilot's checks:
They belong to the first lecture repository that adopts the action: preview-workers: the pilot checks for the first lecture repository that adopts it #299.
A stub of the Cloudflare API that runs the real wrangler through an upload: harness: run the pinned wrangler through a deploy, against a stub of the Cloudflare API #282, low priority.
preview-cloudflare.md, left as it is, and theci.ymldefault, which stays Netlify.Closes #145
🤖 Generated with Claude Code
https://claude.ai/code/session_01WT8bMaHSAzv2LkwwAaSboE