Skip to content

feat: deploy-cloudflare — publish private sites to a Worker behind Access, and prove they are gated (#163) - #176

Merged
mmcky merged 5 commits into
mainfrom
claude/pensive-gauss-4xxo7v
Sep 24, 2026
Merged

mmcky merged 5 commits into
mainfrom
claude/pensive-gauss-4xxo7v

Conversation

@quantecon-services

Copy link
Copy Markdown
Collaborator

Closes #163.

Adds deploy-cloudflare, a new action that publishes a built site to an existing Cloudflare Worker behind Cloudflare Access and fails the job unless the site is proven gated. It runs on push, schedule and workflow_dispatch. preview-cloudflare is untouched and stays PR-only.

What it does

  1. Validates inputs. worker-name, account-subdomain and alias must be valid hostname labels, since the URLs are built from them. team-domain must be a *.cloudflareaccess.com login domain. require-access must be exactly true or false. build-dir must exist and hold files. An empty token is reported as the fork/Dependabot case.
  2. Checks the gate before uploading. An unauthenticated request to https://{worker}.{subdomain}.workers.dev/ must be redirected to exactly team-domain. If it isn't, the action refuses and nothing is uploaded. This covers a Worker that doesn't exist (a mistyped name, which a token broader than the README's would otherwise create, ungated), one that is public, and one gated by the wrong Access organisation.
  3. Installs wrangler 4.136.3 with npm ci from deploy-cloudflare/package-lock.json into RUNNER_TEMP. Node 24 is set up only if the runner has less than 22.
  4. Writes the config and deploys. write-config.js writes {name, compatibility_date, assets.directory, workers_dev, preview_urls}, then wrangler deploy --config runs. wrangler's output is teed to the log rather than captured into a variable, so its errors reach the log (fix(preview): surface deploy errors, pin CLIs, remove unsafe fork guidance #105).
  5. Checks the gate again after deploying, on production and on the new version's own preview URL, https://<version>-{worker}.{subdomain}.workers.dev. Every deploy gets one, because the config enables preview URLs, and an Access setup covering only the production hostname would leave it public. The address comes from wrangler's Current Version ID line, and the check fails closed if that line is missing. The check also runs when wrangler deploy fails, because wrangler can exit with an error after the new version is already live.
  6. Optional alias. With alias, it runs wrangler versions upload --preview-alias and then checks the alias URL's gate.
  7. Writes a job summary in every outcome, including "refused, nothing uploaded" and "deployed, but not gated".

Each gate check probes the root and one real non-HTML file from the build, so a gate that covers only the document root can't pass. scripts/check-access-gate.sh is the probe from the #163 comment, generalised to several URLs:

  • It never follows redirects.
  • It passes only when the Location host equals the team domain.
  • A 2xx gets its own loud "THE SITE IS PUBLIC" failure.
  • 404, 5xx, same-host redirects, a missing Location, a Location hiding its host behind userinfo or a backslash, and unreachable hosts all fail closed.
  • An empty or malformed team domain is a usage error (exit 2).

Decisions (settled in review of #163)

  • Gate check before and after deploying. The spec relied on the token scope to stop a deploy to a new, ungated Worker. The check before uploading prevents it whatever the token can do.
  • wrangler pinned via lockfile, with a Dependabot npm entry for /deploy-cloudflare. /deploy-cloudflare is also added to the github-actions directories, for actions/setup-node.
  • Alias checked after its upload, not before. Whether Access redirects an alias hostname that doesn't exist yet couldn't be verified from here.
  • Auto-picked asset probe: the first file in sorted order with a URL-safe path, skipping dotfiles and HTML.
  • No custom-domain input. Domains stay in the dashboard, and the generated config declares no routes, so wrangler leaves them alone (checked in wrangler 4.136.3's triggersDeploy).
  • deploy-cloudflare: publish private sites to a Cloudflare Worker behind Access, and prove they are gated #163's example alias 2026-08 is invalid. Cloudflare requires an alias to start with a lowercase letter, and wrangler doesn't check before uploading. The action validates this up front, and the docs use report-2026-08.

Tests

Four new harness jobs, all wired into Action harness: all checks. None needs a Cloudflare account:

Job Proves
dc-gate-probe The probe, run against a local stand-in (.github/fixtures/access-gate/server.py), passes only a redirect to the exact team domain. It fails on a wrong org, a public 2xx, a same-host redirect, no Location, a Location hiding its host behind userinfo, 404, 5xx, an unreachable host, an empty team domain, and a public asset behind a gated root, and each failure prints the expected message.
dc-refuses-ungated A real request to a nonexistent workers.dev Worker is refused, and $RUNNER_TEMP/deploy-cloudflare never exists, so wrangler was never even installed. A positive control then runs the same inputs with the gate off: they reach the wrangler install and the config, which proves the refusal came from the gate check.
dc-inputs Seven invalid inputs each fail in validation with no deploy-url, and nothing is installed. Six cases run with the gate off, so a validation rule that went missing can't hide behind the gate check.
dc-wrangler-config The pinned wrangler accepts write-config.js's output for deploy --dry-run and versions upload --preview-alias --dry-run, with no Unexpected fields warning. This is the check a Dependabot bump of the lockfile runs against.

Two adversarial review passes ran over the branch before this PR: five reviewers across security, composite mechanics, the harness, docs and wrangler behaviour, then two reviewers on the fix commit, with every finding checked by an independent skeptic. The last two commits fix what survived.

The most significant fixes:

  • The version preview URL check described above.
  • The post-deploy check now runs even when wrangler fails.
  • An empty team domain used to match a 302 with no Location.
  • A Location could hide its real host behind userinfo.
  • A bash -e abort at the wrangler | tee pipeline skipped the error handling.

Verified locally before pushing:

  • A small composite-step runner ran the action's own steps end to end. It covered:
    • the happy path with an alias, and wrangler dry-runs against the generated config;
    • refusal on public and missing Workers;
    • a failing gate after the deploy, including a public version preview behind a gated production;
    • a missing version ID;
    • wrangler failing after the upload, with and without a version ID;
    • a wrong-org gate on the alias;
    • require-access: false;
    • all fourteen invalid-input cases.
  • The dc-gate-probe script passes, and fails when an expectation is deliberately wrong.
  • shellcheck passes on every run: block.
  • actionlint shows no new findings; the one it reports also exists on main.

Not verified here

  • A real deploy. It needs a gated Worker and a per-Worker Editor token, so the first consumer run (status-projects collect.yml, QuantEcon/status-projects#107) is its proof. The part I'm least sure of is whether wrangler's deploy path succeeds with a per-Worker Editor token. wrangler 4.136.3 tolerates an unauthorised account-level workers/subdomain lookup in some paths, but I couldn't exercise it.
  • The Current Version ID line format was confirmed against wrangler 4.136.3's source, but not against a live deploy's output.

🤖 Generated with Claude Code

https://claude.ai/code/session_01JxLZgJNNxNmNmeUUiD3SBW


Generated by Claude Code

…#163)

Work in progress, not yet ready for review. In this commit:

- deploy-cloudflare/action.yml: validates inputs, checks the Access gate
  before uploading (refuses a missing, public or wrongly gated Worker),
  sets up Node only if <22, installs wrangler with npm ci from the
  committed lockfile, writes a wrangler.jsonc into RUNNER_TEMP, deploys,
  checks the gate after the deploy (root + one non-HTML asset), uploads
  and checks an optional preview alias, and writes a job summary.
- deploy-cloudflare/package.json + package-lock.json: wrangler 4.136.3.
- scripts/check-access-gate.sh: the pilot's probe, generalised to
  several URLs; exact team-domain match, loud failure on 2xx, no -L.
- .github/fixtures/access-gate/server.py: local stand-in for each gate
  response shape, for the harness.

Still to do: harness jobs, README/CHANGELOG/TESTING/dependabot docs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JxLZgJNNxNmNmeUUiD3SBW
…#163)

- deploy-cloudflare/write-config.js: the generated wrangler config, moved
  out of an inline `node -e` so the harness dry-runs the exact file the
  action uses.
- test-actions.yml: dc-gate-probe (every gate response shape against a
  local stand-in), dc-refuses-ungated (an ungated Worker is refused before
  wrangler is installed), dc-inputs (every invalid input fails in
  validation), dc-wrangler-config (the pinned wrangler accepts the
  generated config); all wired into harness-summary.
- dependabot.yml: npm ecosystem for /deploy-cloudflare; the directory is
  added to the github-actions list for actions/setup-node.
- deploy-cloudflare/README.md with the setup checklist; README, CHANGELOG,
  TESTING, QUICK-REFERENCE, ARCHITECTURE and copilot-instructions entries.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JxLZgJNNxNmNmeUUiD3SBW
…ailed deploy (#163)

From an adversarial review of the branch:

- Every deploy gets its own preview URL (preview_urls: true), which no
  check covered when no alias was given. The check after deploying now
  probes https://<version>-<worker>.<subdomain>.workers.dev too, from the
  "Current Version ID" wrangler prints, and fails closed if it is missing.
- wrangler can exit non-zero after the new version is live, which used to
  skip the check after deploying. It now runs whenever wrangler was
  attempted, and the summary says the build may be live.
- check-access-gate.sh refuses an empty or malformed team domain (exit 2;
  an empty team matched a Location-less 302) and a Location whose host is
  hidden behind userinfo or a backslash.
- build-dir may not contain line breaks, which would inject outputs.
- Harness: dc-inputs sets require-access: 'false' on every case but one,
  so a dropped validation rule cannot hide behind the gate check;
  dc-refuses-ungated gains a positive control showing the same inputs reach
  wrangler with the gate off; dc-wrangler-config fails on wrangler's
  "Unexpected fields" warning; dc-gate-probe covers the new cases.
- Docs brought in line: require-access covers every check, troubleshooting
  names every refusal message, copilot-instructions counts 8 actions.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JxLZgJNNxNmNmeUUiD3SBW
…angler pipeline (#163)

From a second review of the fix commit:

- The runner starts steps with `bash -e`, so a failing
  `wrangler deploy | tee` ended the step before the exit status, the
  version id and the ::error:: annotation were read. The pipeline now runs
  under `set +e`.
- A missing "Current Version ID" now fails the check after deploying in
  every case, not only after a successful deploy: wrangler prints the id
  only once every post-upload step has succeeded, so most failed deploys
  lack it, and the version's preview URL was then skipped silently.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JxLZgJNNxNmNmeUUiD3SBW

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.

Copilot review overview

🔵 Needs a closer look

It introduces a large, security-critical new action that gates private content, and its real-deploy path against a gated Worker with a per-Worker Editor token is explicitly unexercised in CI, so a human should verify that path before approval.

Review effort: Balanced
Findings: None

What changed in this PR

This PR adds a new composite action, deploy-cloudflare, that publishes a built site to an existing Cloudflare Worker behind Cloudflare Access and fails the job unless the site is provably gated (an unauthenticated request must redirect to exactly the configured <team>.cloudflareaccess.com). It complements the existing PR-only preview-cloudflare and fills the "members-only site" gap that GitHub Pages cannot cover on the org's Team plan. The action validates inputs, checks the gate before uploading (fail-closed prevention), installs a lockfile-pinned wrangler, generates a per-run config, deploys, and re-checks the gate on production, the new version's preview URL, and any alias — writing a job summary in every outcome.

Changes:

  • New action: deploy-cloudflare/ (action.yml, write-config.js, pinned package.json/package-lock.json, README) plus the shared scripts/check-access-gate.sh probe.
  • CI: four harness jobs (dc-gate-probe, dc-refuses-ungated, dc-inputs, dc-wrangler-config) wired into the required Action harness: all checks, with a local Python gate stand-in fixture; Dependabot gains an npm ecosystem entry for the wrangler lockfile.
  • Docs: README, QUICK-REFERENCE, ARCHITECTURE, TESTING, CHANGELOG and copilot-instructions updated for the new action.
File Description
deploy-cloudflare/​action.yml Core composite action: input validation, gate checks before/after deploy and on alias, tee'd wrangler deploy, job summary.
scripts/​check-access-gate.sh Probe that passes only a redirect to the exact team domain; handles 2xx/404/5xx, userinfo/backslash, unreachable, empty team.
deploy-cloudflare/​write-config.js Generates the minimal per-run wrangler config (assets-only, workers_dev + preview_urls).
deploy-cloudflare/​package.json /​ package-lock.json Pins wrangler 4.136.3 for npm ci.
deploy-cloudflare/​README.md Usage, inputs/outputs, gate-check semantics, setup checklist, troubleshooting.
.github/​workflows/​test-actions.yml Four new harness jobs + anchor needs wiring.
.github/​fixtures/​access-gate/​server.py Local stand-in emitting each gate response shape for the probe test.
.github/​dependabot.yml Adds /deploy-cloudflare to github-actions dirs and a new npm ecosystem block.
README.md, docs/​QUICK-REFERENCE.md, docs/​ARCHITECTURE.md, TESTING.md, CHANGELOG.md, .github/​copilot-instructions.md Documentation and inventory updates for the new action.
Files not reviewed (1)
  • deploy-cloudflare/package-lock.json: Generated file

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

…4xxo7v

Resolves the two conflicts with main after #173 and #175 landed: the
copilot-instructions status block keeps main's refreshed release and container
lines with this branch's "8 composite actions" line, and the CHANGELOG's
[Unreleased] Added section carries both sets of entries.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@mmcky
mmcky merged commit 3cbab39 into main Sep 24, 2026
23 checks passed
@mmcky
mmcky deleted the claude/pensive-gauss-4xxo7v branch September 24, 2026 00:45
mmcky added a commit that referenced this pull request Sep 24, 2026
…ploy

Resolves the conflicts with #176: test-actions.yml keeps the four
deploy-cloudflare harness jobs and this branch's preview-cli-install job,
with all five in harness-summary's needs; TESTING.md keeps the
deploy-cloudflare row and this branch's split of the preview-* and
publish-gh-pages rows.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@mmcky

mmcky commented Sep 30, 2026

Copy link
Copy Markdown
Contributor

First live run: QuantEcon/project-qep7

A live deploy has now answered both points under Not verified here. QuantEcon/project-qep7 became the first consumer, ahead of QuantEcon/status-projects#107. Its end-to-end test is recorded on QuantEcon/project-qep7#7.

  • A real deploy with a per-Worker Editor token works. The token had one policy, Individual Workers Editor on project-qep7-report, and no account-level permission. wrangler deploy (4.136.3, from the lockfile) uploaded and deployed with workers_dev and preview_urls on, and every post-deploy check passed: the test run 36647686611 and the first deploy from main, 36648331879.
  • The Current Version ID line matches. The live output was Current Version ID: 28b2e956-ce5f-4bff-a6c5-629cf7e5fcdc, and the action checked https://28b2e956-project-qep7-report.quantecon.workers.dev/ and /build-info.json. Wrangler 4.142.0 run locally prints the same form.
  • Refusal on a missing Worker behaved as documented: answered 404 on / and /build-info.json, "Refusing to deploy", and nothing uploaded (36647502545).

Still not exercised: the alias path, including whether Access redirects an alias hostname before its first upload.

Assisted-by: Claude Code (Claude Opus 5.5)

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.

deploy-cloudflare: publish private sites to a Cloudflare Worker behind Access, and prove they are gated

4 participants