Skip to content

feat(preview-workers): preview a pull request on a Cloudflare Worker (#145) - #298

Merged
mmcky merged 4 commits into
mainfrom
feat/145-preview-workers
Nov 10, 2026
Merged

mmcky merged 4 commits into
mainfrom
feat/145-preview-workers

Conversation

@mmcky

@mmcky mmcky commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

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 a platform: input on preview-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-workers runs wrangler 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 at https://pr-<number>-<worker-name>.<account-subdomain>.workers.dev. Most of the action is calls to code already on main:

  • the trust gate (scripts/preview-decide.sh), change detection, and the comment and placeholder (scripts/preview-comment.cjs, which gets a workers provider);
  • deploy-cloudflare's config writer, moved to scripts/;
  • 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-url from its inputs, as the placeholder does. The pinned wrangler (4.158.0, as on main since #294) appends a version-upload record 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:

wrangler's record Means The action
The alias URL equals the built one All is well Sets deploy-url, and deployment-url from the record's version URL when it is of the expected form, else empty with a warning
Another alias URL account-subdomain is wrong. The subdomain is one per account, so unlike #216's Pages addresses it cannot legitimately differ Fails, naming both URLs
No alias URL The Worker's preview URLs are off, and versions upload does not turn them on Fails, saying where to turn them on
No record at all A wrangler that writes none Warns, and sets the built deploy-url unchecked, with deployment-url empty: #216's fallback

Changes

File Change
preview-workers/action.yml (new) The decision, then the input check, then change detection, the install, the upload, and the comment. All follow preview-cloudflare's conditions. Inputs: cloudflare-api-token, cloudflare-account-id and build-dir, needed only for a deploy, so the placeholder's job holds no secret; worker-name and account-subdomain, required; lectures-dir, dispatch-alias and placeholder. Outputs: preview-cloudflare's four. The input check runs on every event: the Worker's name and subdomain must be hostname labels, and a dispatch-alias must fit in one with the name. For a deploy, pr-<number> must fit too, and the secrets and build-dir are needed. The install is npm ci from the lockfile into RUNNER_TEMP, with nothing added to PATH. The upload writes the config, runs versions upload, prints and reads the record, and checks the URL as in the table above
preview-workers/package.json, package-lock.json (new) wrangler 4.158.0. The lockfile is main's preview-cloudflare lockfile with the package renamed
scripts/write-wrangler-config.js Moved from deploy-cloudflare/write-config.js in a commit of its own, so git log --follow keeps 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 callers
deploy-cloudflare/action.yml Calls the writer at its new path. No change to what it does: the config it writes differs only in that comment line, and the dc-* jobs pass
scripts/preview-comment.cjs A workers provider: ## ☁️ Cloudflare Workers Preview Ready!, ## ⏳ Cloudflare Workers Preview Building…, the marker <!-- quantecon-preview:workers -->, and previewUrl https://<alias>-<site>.workers.dev with the site <worker>.<subdomain>
scripts/preview-decide.sh, scripts/detect-changed-lectures.sh Comments only: the third caller, and that preview-workers checks the 63-character rule itself
.github/workflows/test-actions.yml New jobs preview-workers-url and preview-workers-config (below). preview-workers cases added to preview-comment, preview-wiring and preview-cli-install. dc-wrangler-config uses the writer's new path. The gate's MUST_RUN lists the new lockfile and the writer, and the two new jobs are in harness-summary's needs: beside preview-cloudflare-url
.github/fixtures/preview-comment/test.cjs, workers-*.md (new) The marker, wiring, two ready fixtures and one pending fixture, four lookup cases, and 22 input-check cases, for 91 cases in all. A case can now also assert what the check writes to GITHUB_OUTPUT. No earlier version rendered the workers-* fixtures, so the shared script rendered them and I read them by eye. They differ from the Cloudflare ones only in heading and host
docs/user/actions/preview-workers.md (new), preview-workers/README.md (new) The chapter: setting up the Worker, its preview URLs, the name-length rule, and the token, made under Manage account, Account API tokens, with Individual Workers Editor scoped to Specified Workers; three examples; Behaviour; What fails the job; Security; Troubleshooting. Then the generator
docs/user/actions/deploy-cloudflare.md Step 4 gives the same route to a per-Worker token
docs/user/README.md, scripts/generate-docs.py preview-workers in ORDER after preview-cloudflare, and the generated index row
docs/user/composition.md, docs/user/getting-started.md One mention each beside the other two preview actions
templates/ci.yml A commented "Cloudflare Workers Alternative" block in the placeholder and deploy jobs, beside the Pages ones. It is inert until someone uncomments it
.github/dependabot.yml /preview-workers in the npm directories
docs/dev/ARCHITECTURE.md, docs/dev/TESTING.md, docs/dev/PLAN.md Ten actions; the config writer among the shared scripts; the preview-* row; #145 out of PLAN's open issues
CHANGELOG.md A new ### Added under [Unreleased], above #290's ### Changed. 15 insertions, 0 deletions, and everything from ## [0.17.0] down is byte-identical to main

The harness

A pull request's harness has no Cloudflare secrets, so the jobs cover everything short of a real upload:

  • preview-workers-url runs the deploy step from action.yml against a stub wrangler. The stub refuses any command line but versions 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's version-upload line. There are 13 cases:

    • a match, on a pull request and on a dispatch;
    • another subdomain, another alias, and no alias URL, each of which must fail;
    • no record, and an unknown record version, which must warn;
    • three malformed version URLs;
    • a line break in either URL, which must never start a workflow command;
    • a failed upload.

    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-config installs preview-workers' own lockfile, writes the config with the moved writer, and dry-runs versions upload --preview-alias pr-5 with WRANGLER_OUTPUT_FILE_PATH. It asserts that there are no "Unexpected fields", and exactly one version-upload record 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-comment covers:

    • the wiring of the two comment steps;
    • the three fixtures;
    • the placeholder and the deploy sharing one comment;
    • preview-workers and preview-cloudflare never taking each other's comment, though their headings start the same way;
    • every input rule, at its boundary: a 54-character name on pull request 99999 fits, 55 does not, the same for the placeholder, and not checked on a fork's run that deploys nothing. Also a 28-character dispatch-alias with a 34-character name, then a 35-character one, the subdomain's three accepted forms, and line breaks.
  • preview-wiring has three new steps:

    • a too-long dispatch-alias and a bad placeholder each fail before any install;
    • a deploy without its account ID fails before any install;
    • a valid run on this event installs the CLI and fails at Cloudflare on the fake credentials, exactly when the decision says it deploys.

    preview-workers adds nothing to PATH, so that check looks for npm's own link of wrangler.

Each new case fails on the code it guards against. A throwaway workflow on scratch/145-red (run 42765623274, the branch since deleted) first ran preview-comment and preview-workers-url on this branch's code, which passed. It then broke one thing at a time, and passed only if the covering job then failed:

Broken Failed, as it should
main's preview-comment.cjs, with no workers provider preview-comment: 6 cases, with PROVIDER is [workers], not one of: netlify, cloudflare
The 63-character check removed preview-comment: the 55-character name for a deploy, the same for the placeholder, and the 28 + 35 dispatch-alias
The record check skipped preview-workers-url: other-subdomain, other-alias and alias-line-break
deploy-url built without the Worker's name preview-workers-url: every case that sets a URL
A record with no version-upload line preview-workers-config's own check

What 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:

  • The URL scheme, on the real Worker: 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.
  • The record, in the pinned wrangler: I read 4.156.1's source, and again 4.158.0's after deps: Bump the npm group across 3 directories with 2 updates #294. versions upload writes version-upload, version 1, with version_id, preview_url and preview_alias_url. The URLs are built from the API's preview_url_suffix, and left out when the Worker's preview URLs are off. I ran the dry run locally on both versions.
  • What versions upload will not do: it refuses a Worker that does not exist, whatever the token can do. It applies no routes, workers_dev or preview_urls: only wrangler deploy does. And it never sends production traffic to the version.
  • The move breaks no caller: gh search code write-config.js --owner QuantEcon finds only this repository, and preview-workers is not used anywhere yet.
  • On the real Worker: the four canary runs in the next section, all green at 709572d: a pull request, a second push, a dispatch, and a wrong subdomain failing.
  • CI: Action harness: all checks is green on 709572d (run 42767031661), with every dc-* job passing on the moved writer.
  • Locally:
    • python3 scripts/generate-docs.py --check --check-examples --actionlint …, actionlint with shellcheck, and python3 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-config and dc-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:

  • placeholder: posts the pending comment, and records its id;
  • deploy: waits for it, builds a two-page site that names the run, uploads it, and asserts what the action did.

All four legs passed at 709572d. The canary PR was #83, now closed with the results, and its branch deleted:

Leg Run What it showed
1. The pull request opened 42766349959, at 0cc12c0 The pending comment, then the deploy replacing it in place (the same comment id), with the ready heading, the commit, the lecture link and the version. deployed: 'true', and deploy-url exactly https://pr-83-qe-preview-canary.quantecon.workers.dev, serving the run. deployment-url https://8815c202-qe-preview-canary.quantecon.workers.dev, serving the run. changed-files listed lectures/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.html with a 307 to /about, which a browser follows and the check's curl did not. Its printed record is now the harness fixture's line (709572d)
2. A second push 42767402582 The same assertions, with the check following redirects. The alias moved to the new version (c2470a79), while run 1's version URL, 8815c202-…, still served run 1's build. The lecture link ended at /about, on the same host
3. A dispatch 42767505288 dispatch-canary-workers, deployed: 'true', no comment, and production untouched
4. A dispatch with account-subdomain: quantecon-wrong 42767597103 The action failed after the upload, with Cloudflare serves this preview at [https://dispatch-canary-workers-qe-preview-canary.quantecon.workers.dev], not at …quantecon-wrong…, deployed: 'false' and no deploy-url

At v0.18.0's staged release, the same run against the tag. After the release, a preview-workers step joins the canary's ci.yml beside preview-cloudflare, so later staged releases exercise it.

What to watch after merge

  • Nothing changes for an existing caller: no caller uses preview-workers, and deploy-cloudflare behaves as before.
  • Dependabot's npm group now covers four directories, and a wrangler bump meets preview-workers-config as well as dc-wrangler-config.
  • The PR touches none of setup-environment/, build-lectures/, containers/** or the lecture matrix.

Not in this PR

Closes #145

🤖 Generated with Claude Code

https://claude.ai/code/session_01WT8bMaHSAzv2LkwwAaSboE

mmcky and others added 3 commits November 10, 2026 16:57
…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

Copilot AI 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.

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 updates deploy-cloudflare and 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
mmcky merged commit 4d4261e into main Nov 10, 2026
68 checks passed
@mmcky
mmcky deleted the feat/145-preview-workers branch November 10, 2026 06:21
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>
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.

Add Workers static assets support to the Cloudflare preview action

2 participants