Skip to content

feat(deploy-cloudflare): a visibility input, private or public, checked both ways (#177) - #244

Merged
mmcky merged 3 commits into
mainfrom
feat/177-visibility-input
Nov 5, 2026
Merged

mmcky merged 3 commits into
mainfrom
feat/177-visibility-input

Conversation

@mmcky

@mmcky mmcky commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

deploy-cloudflare could only prove a site private. To deploy a public site you had to pass require-access: 'false', which skips every check and needs a dummy team-domain, so nothing verified what was published. This PR adds a visibility input, private or public, as #177 proposes. The action checks the live site against it in both directions, so a private site found public fails, and so does a public site found gated. require-access shipped in v0.12.0, so per the 2026-11-04 decision it stays for one release as a deprecated alias.

Changes

File Change
deploy-cloudflare/action.yml New visibility input and output. team-domain is no longer a required input; validation requires it for private and rejects it for public. require-access is deprecated and its default goes from 'true' to '', so that "not passed" can be told apart. The three checks (before the upload, after the deploy, on the alias) run in either mode, and only an explicit unchecked (require-access: 'false') skips them. The mode is the first log line and the job summary's heading.
scripts/check-access-gate.sh Gains --public: an anonymous request must get a 2xx without a redirect, and a redirect to any *.cloudflareaccess.com fails loudly as THE SITE IS BEHIND ACCESS. Also --allow-404, for the check before the deploy (see below). The gated mode is unchanged, apart from the redirect-host parsing moving into a function both modes share.
.github/fixtures/access-gate/server.py A Host of harness-<shape>.… answers as /<shape>…, and it can serve TLS, so the action itself can run against a stand-in gated or public Worker.
.github/workflows/test-actions.yml dc-gate-probe: 16 new probe cases (14 → 30). dc-refuses-ungated: visibility: private, plus both deprecated forms. dc-inputs: five new rejected cases (12 in all), now asserting through the visibility output that each was rejected in validation. New job dc-refuses-mismatch (added to harness-summary after dc-wrangler-config).
docs/user/actions/deploy-cloudflare.md Intro, when to use it, the setup checklist per mode, a public example, behaviour per mode, the public verdict table and the no-index.html rule, a "Moving from require-access" section, and troubleshooting for every new error. The input and output tables are regenerated.
deploy-cloudflare/README.md, docs/user/README.md Regenerated from the new action description.
CHANGELOG.md ### Added (visibility) and ### Deprecated (require-access, and passing neither input), both new under [Unreleased].

Decisions for the reviewer

These interpret the brief or settle #177's open questions. The organiser agreed the first one, and is flagging it to the maintainer too.

1. The deprecation rule. Passing neither input warns rather than fails in this release.

visibility require-access Result
private or public not passed that mode
private or public passed ❌ "visibility and require-access are both set. require-access is deprecated: remove it, and keep visibility: …"
not passed 'true' private, with a deprecation warning
not passed 'false' today's skip-all, with a deprecation warning and the existing "never use this for private content" warning
not passed not passed private, with a warning to add visibility
anything else any ❌ "visibility must be private or public"
not passed anything else ❌ "require-access must be 'true' or 'false'"

Why "neither" warns: both known callers (private repositories) pass neither input and rely on require-access's default. A caller that passes neither is relying on the alias's default, so it falls inside the one-release protection decision 10 gives the alias. Failing it would break both callers as soon as they bump, which is exactly what the alias exists to prevent. Private is also the fail-safe direction, since every check still runs. Flipping it to an error is one line (the ''|true) branch of the validation step's case) plus one harness case (the neither step in dc-refuses-ungated would move to dc-inputs).

Why require-access: 'false' keeps skipping every check rather than map to public: mapping it to public would run the inverted checks, which would newly fail a caller whose site is in fact gated. Its warning says to choose visibility: public or visibility: private, and the chapter's migration table spells out both.

visibility is declared required: false for this release, since the action still accepts it missing. Its description says leaving it out fails from the next minor release. Declaring it required: true now would make the generated table claim something the action doesn't enforce, and local actionlint would flag the deprecated-form harness cases.

2. A new visibility output. It gives the resolved mode: private or public, or empty when an input is rejected or the checks are off. It is written only once every input has passed, which is what lets the harness tell "rejected in validation" from "refused by the check" in each case. Callers also get the alias's resolution in machine-readable form. It is new public surface; if you'd rather not have it, the harness falls back to the old indirect signal (whether wrangler got installed).

3. A build with no index.html (#177's open question). Without an index.html the root answers 404 even when the site is served. In public mode, the checks after the deploy and on the alias then request the probe file alone, with a warning saying so. A public build-dir with neither an index.html nor a probe-able file fails validation, since nothing could show it is served. The action fails closed here, as it does elsewhere. Private mode is unchanged, because a gate redirects the root either way.

4. The public check before the upload lets a 404 pass (--allow-404). The version live at that point need not hold this build's files: a new probe file, or a previous build without index.html, would answer 404 on a correctly set-up public Worker. If the check refused that, the next deploy could never fix it. So the check before the upload refuses only a Worker that answers as one behind Access (or with an error), which is the case worth preventing: a private site's Worker named by mistake would otherwise be overwritten with a public build. The cost: a public Worker that does not exist passes this check and fails at wrangler deploy instead, because the manual's per-Worker token cannot create one (#177's second open question). The setup checklist now says that for a public site the token, not the check, is what stops a mistyped name.

5. --public in check-access-gate.sh, not a sibling script. The curl call, retry policy, no--L rule and redirect-host parsing (including the userinfo and backslash refusal) are exactly what the public check needs as well. A second script would duplicate them, and the two could drift apart. Each mode keeps its own verdict case, so the gated verdicts did not change.

6. The mismatch case runs the action against a stand-in, not real workers.dev. There is no gated or public workers.dev Worker this public repository can name. dc-refuses-mismatch therefore points harness-gated.quantecon-harness-local.workers.dev and harness-public.… at the fixture through /etc/hosts, over TLS with a throwaway self-signed certificate added to the runner's trust store, on port 443 (opened by lowering ip_unprivileged_port_start). It asserts that public against the gated Worker, and private against the public one, are refused before wrangler is installed. Then a positive control for each mode: the matching Worker passes the check and reaches wrangler, which fails on the fake token. The action has no test hook for this; it is the real composite run.

What I checked, and how

  • The probe's verdict logic, all 30 dc-gate-probe cases, run locally. The sandbox here blocks binding a local port, so the fixture server could not run. Instead a stub curl answered each fixture path exactly as server.py does. Every case gave the expected exit code and message. The real server runs in CI.
  • The validation step, extracted from action.yml and run on 19 input combinations: every row of the table above, both cross-checks, a bad team-domain, a public and a private build without index.html, an HTML-only public build, and an empty token. Each gave the expected exit code, message and outputs (mode, visibility, probe-root). Whenever validation got as far as resolving the mode, the mode line was the first line of output.
  • The three check steps and the summary, extracted and run with the stub curl. Covered: private and public against gated, public and missing Worker shapes, a missing version ID, the root-less public probe, and the summary in every mode.
  • shellcheck 0.10.0 on check-access-gate.sh and on every run: block of the action: clean, apart from one SC2015 info on the unchanged probe-path line, which main has too.
  • actionlint 1.7.12 on test-actions.yml: clean, apart from one SC2086 info in the gate job, which main has too. It also validated every new with: against the action's declared inputs.
  • python scripts/generate-docs.py --check, and --check-examples --actionlint: generated docs current, and the 46 action steps and 14 complete workflows in the docs and templates pass.
  • In CI (run 41816345288), all 30 checks pass. I read the deploy-cloudflare job logs to confirm each case failed for the reason it claims, not for some other one:
    • dc-refuses-mismatch: the stand-in answers through the real probe over TLS (PASS 302 on the gated host, PASS 200 on the public one). public against the gated Worker is refused with THE SITE IS BEHIND ACCESS, and private against the public one with THE SITE IS PUBLIC, both before wrangler is installed. Both controls pass their check and reach wrangler deploy, which fails on the fake token as intended. Each run's first log line is its mode.
    • dc-inputs: all 12 cases are rejected in validation, each with its own message (for example visibility must be private or public, got [Public], team-domain is set, but visibility is public — did you mean private?). Every case's visibility output is empty.
    • dc-refuses-ungated: visibility: private, neither input and require-access: 'true' are all checked as private and refused. The nonexistent workers.dev hostname is unreachable, as it is on main.

What to watch after merge

  • Nothing deploys on merge. The action has no caller in this repository.
  • The two known callers pin @v0.12.0, so nothing changes for them until they bump. When they do, each run warns that visibility is not set; adding visibility: private silences it, and should happen before the alias is removed.
  • The first real public deploy is the first proof of public mode against Cloudflare itself. Without an account, the harness can prove the logic but not what Cloudflare actually answers. In particular, the public check after the deploy assumes a correctly served Worker answers its root and probe file with a 2xx, not a redirect. That holds with the generated config (html_handling left at its default and non-HTML probe files), but no public Worker has run it yet.

Not in this PR

Closes #177

🤖 Generated with Claude Code

https://claude.ai/code/session_01WT8bMasGPpqd8PDs7Fxs5m

Copilot AI balanced review requested due to automatic review settings November 4, 2026 10:45

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’s public-mode and TLS stand-in verification depends on unvalidated assumptions about Cloudflare’s real unauthenticated responses plus runner-level prerequisites (CA trust, /etc/hosts, sysctl to bind 443), so it needs a maintainer sanity-check and ideally a real public Worker deploy to confirm CI and operational behavior.

No open issues 🎉

What changed in this PR

Adds first-class support for deploying public Cloudflare Workers alongside the existing private (Access-gated) flow by introducing an explicit visibility input (private|public) and enforcing it via live checks before and after deployment, while keeping require-access temporarily as a deprecated alias.

Changes:

  • Introduces visibility: private|public (and a visibility output) in deploy-cloudflare, with validation/deprecation behavior around require-access.
  • Extends scripts/check-access-gate.sh with --public (inverse check) and --allow-404 (for pre-deploy public checks).
  • Expands CI harness coverage (more probe/input cases + a mismatch-refusal job using a local TLS stand-in) and regenerates docs/READMEs + updates CHANGELOG.md.

Final review comments (unresolved):

  • Moderate (votes: 1) — .github/fixtures/access-gate/server.py (around line 37): Host-to-shape routing should strip an optional :port from the Host header to avoid misrouting (e.g., harness-public…:443).
  • Moderate (votes: 1) — .github/fixtures/access-gate/server.py (around line 74): TLS enablement/usage messaging should not silently ignore invalid argument counts; current behavior can start without TLS when TLS was intended.
  • Moderate (votes: 1) — deploy-cloudflare/action.yml (around line 141): In unchecked mode (require-access: 'false'), team-domain is still required/validated despite checks being disabled; consider allowing it to be empty/ignored in this mode.
  • Nit (votes: 1) — scripts/check-access-gate.sh (around line 79): Diagnostics for relative Location headers currently degrade to “”; handle non-absolute locations explicitly to improve debugging.
File Summary
scripts/​check-access-gate.sh Adds --public (anonymous 2xx/no Access redirect) and --allow-404 support while sharing redirect parsing/retry logic across modes.
docs/​user/​README.md Regenerated user docs index/readme to reflect the updated action behavior and documentation.
docs/​user/​actions/​deploy-cloudflare.md Updates the action docs for public/private modes, migration from require-access, behavior tables, troubleshooting, and regenerated inputs/outputs.
deploy-cloudflare/​README.md Regenerated action README to match the new visibility behavior and documentation.
deploy-cloudflare/​action.yml Adds visibility input/output, deprecates require-access, and enforces audience checks pre/post-deploy (unless explicitly unchecked).
CHANGELOG.md Adds [Unreleased] entries for new visibility and deprecations around require-access / missing inputs.
.github/​workflows/​test-actions.yml Expands harness coverage (more probe/input cases) and adds a mismatch-refusal job using a local TLS stand-in.
.github/​fixtures/​access-gate/​server.py Enhances fixture server behavior (Host-based shaping) and optional TLS to support end-to-end harness testing.

Review effort: Balanced

mmcky added a commit that referenced this pull request Nov 4, 2026
…nd refuses a miscounted call

From the Copilot review of #244. A Host with a port now routes by its
first label alone; it already did whenever the name had a dot, which
every name the harness uses has. A call with only one of the
certificate and key files now exits with usage instead of serving plain
HTTP to a job that meant TLS.

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

mmcky commented Nov 4, 2026

Copy link
Copy Markdown
Contributor Author

Replying to the Copilot review above, point by point. It left no inline threads, so I'm answering here.

1. server.py: strip a port from Host before routing. Done in f9ffd2c. In practice it could not misroute: the label is the part before the first dot, and every name the harness uses has dots, so a trailing :443 never reached it. Stripping the port is still more correct, and it costs one call.

2. server.py: don't silently start without TLS on a miscounted call. Done in f9ffd2c. Anything other than <port> or <port> <certfile> <keyfile> now exits with usage. The harness passes both files, so this only guards a future edit.

3. team-domain is still required when require-access: 'false' turns the checks off. Left as it is, on purpose. That path exists only as the deprecated alias, and its contract for this one release is that it behaves exactly as v0.12.0 did, when team-domain was required and validated whatever require-access said. Relaxing it would change a path that is about to go, for no caller: anyone on require-access: 'false' today already passes a team-domain. The new way to deploy a site without Access is visibility: public, which needs no team-domain and rejects one.

4. check-access-gate.sh: a relative Location degrades to <no Location>. It doesn't. curl's %{redirect_url} resolves a relative Location against the request URL, so the probe sees an absolute URL. The fixture's /same-host path sends the relative Location: /public/, and this PR's CI run reports it as answered 307 to '127.0.0.1', in both modes. <no Location> appears only when the header is missing, the /no-location case. This part of the parsing is unchanged from main, apart from moving into a function both modes share.

On the overall note: the probe logic is tested in the harness, but what Cloudflare itself answers is still unproven for public mode. The PR body's "What to watch after merge" says so: the first real public deploy is the first proof.

Claude Code (on behalf of mmcky)

mmcky added a commit that referenced this pull request Nov 4, 2026
…nd refuses a miscounted call

From the Copilot review of #244. A Host with a port now routes by its
first label alone; it already did whenever the name had a dot, which
every name the harness uses has. A call with only one of the
certificate and key files now exits with usage instead of serving plain
HTTP to a job that meant TLS.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WT8bMasGPpqd8PDs7Fxs5m
@mmcky
mmcky force-pushed the feat/177-visibility-input branch from f9ffd2c to b6cd3e5 Compare November 4, 2026 11:03

@mmcky mmcky left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed action.yml, check-access-gate.sh, the fixture and the three harness jobs against main. The validation case matches the table in the body row for row, each of the three checks keeps the private verdicts unchanged and adds the public ones, the summary's gate() resolves every mode:outcome pair that can occur, and the mismatch job's two refusals and two controls are attributed the way the body says. The Copilot points were handled correctly, including keeping team-domain required under the deprecated require-access: 'false'. Nothing to change.

On the decisions for review:

Decision Verdict
1. Neither input warns and checks as private Agreed. Both known callers rely on the alias's default, and private is the direction in which every check still runs. Flip it to an error in the release that removes require-access.
2. The visibility output Keep it. It is what lets dc-inputs tell a validation rejection from a check refusal, and a caller asserting visibility == 'public' is a cheaper guard than reading the log.
3. No index.html: probe the file alone after the deploy, and fail with neither Agreed; failing closed matches the rest of the action.
4. --allow-404 before the upload Agreed. The live version need not hold this build's files, and a mistyped public name failing at wrangler deploy on the per-Worker token is the backstop the checklist now names.
5. --public in the same script Agreed. The redirect-host parsing is the part that must not drift between the two modes.
6. The stand-in over TLS behind /etc/hosts Fine on hosted runners, which is where the harness runs. It edits the runner's CA store, /etc/hosts and a sysctl, so the job must stay on ubuntu-latest; a one-line comment saying so would stop a later move to a self-hosted runner.

The one claim the harness cannot make, that a correctly served public Worker answers its root and probe file with a 2xx and no redirect, holds for the generated config: html_handling stays at its default, so / serves index.html directly, and the probe file is never HTML, so the trailing-slash redirect cannot apply to it. The first real public deploy remains the proof, as the body says.

Claude Code (on behalf of mmcky)

mmcky added a commit that referenced this pull request Nov 4, 2026
…ted runner

From the maintainer's review of #244. The stand-in edits the runner's
CA store, /etc/hosts and a sysctl, which a self-hosted runner would
keep between jobs, so the job must stay on ubuntu-latest.

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

mmcky commented Nov 4, 2026

Copy link
Copy Markdown
Contributor Author

Thanks for the review. On point 6: done in 6964a5e. dc-refuses-mismatch now carries a comment above its runs-on: saying it needs a GitHub-hosted runner, because the stand-in edits the runner's CA store, /etc/hosts and a sysctl, which a self-hosted runner would keep between jobs. That commit changes only those two comment lines.

On decision 1: the removal is the follow-up the PR body names under "Not in this PR", and the organiser has it for the work plan. That release flips "neither input" to an error, drops require-access, makes visibility required, and moves the neither case from dc-refuses-ungated to dc-inputs.

Claude Code (on behalf of mmcky)

mmcky added a commit that referenced this pull request Nov 5, 2026
…nd refuses a miscounted call

From the Copilot review of #244. A Host with a port now routes by its
first label alone; it already did whenever the name had a dot, which
every name the harness uses has. A call with only one of the
certificate and key files now exits with usage instead of serving plain
HTTP to a job that meant TLS.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WT8bMasGPpqd8PDs7Fxs5m
mmcky added a commit that referenced this pull request Nov 5, 2026
…ted runner

From the maintainer's review of #244. The stand-in edits the runner's
CA store, /etc/hosts and a sysctl, which a self-hosted runner would
keep between jobs, so the job must stay on ubuntu-latest.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WT8bMasGPpqd8PDs7Fxs5m
@mmcky
mmcky force-pushed the feat/177-visibility-input branch from 6964a5e to 720355e Compare November 5, 2026 00:32
mmcky added a commit that referenced this pull request Nov 5, 2026
…nd refuses a miscounted call

From the Copilot review of #244. A Host with a port now routes by its
first label alone; it already did whenever the name had a dot, which
every name the harness uses has. A call with only one of the
certificate and key files now exits with usage instead of serving plain
HTTP to a job that meant TLS.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WT8bMasGPpqd8PDs7Fxs5m
@mmcky
mmcky force-pushed the feat/177-visibility-input branch from 720355e to 397deaf Compare November 5, 2026 00:36
mmcky added a commit that referenced this pull request Nov 5, 2026
…ted runner

From the maintainer's review of #244. The stand-in edits the runner's
CA store, /etc/hosts and a sysctl, which a self-hosted runner would
keep between jobs, so the job must stay on ubuntu-latest.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WT8bMasGPpqd8PDs7Fxs5m
mmcky and others added 3 commits November 5, 2026 11:56
…ed both ways (#177)

deploy-cloudflare could only prove a site private. A public site had to
pass require-access: 'false', which skipped every check, plus a dummy
team-domain. visibility declares the audience at the call site, and the
action checks the live site against it in both directions:

- private: as before, an anonymous request must be redirected to
  team-domain's Access login, before the upload, after the deploy and
  on the alias.
- public: the same three checks inverted. An anonymous request must be
  served the site, and a redirect to any *.cloudflareaccess.com fails.
  The check before the upload lets a 404 pass (the live version need
  not hold this build's files yet), so it refuses only a Worker behind
  Access. That covers a private site's Worker named by mistake.

team-domain is required for private and rejected for public, so a
workflow copied from one kind of site to the other fails in validation.
The mode is the first log line and the job summary's heading, and a new
visibility output reports it. A public build without index.html is
checked on its probe file alone after the deploy; with neither, it
fails validation.

require-access shipped in v0.12.0, so it stays for one release as a
deprecated alias: 'true' and neither input mean private, 'false' keeps
today's skip-all, each with a warning; both inputs together fail.

check-access-gate.sh gains --public and --allow-404. The harness covers
every public verdict (dc-gate-probe), each rejected input (dc-inputs),
the deprecated forms (dc-refuses-ungated), and a new dc-refuses-mismatch
job that runs the action against a gated and a public Worker stood in
for on the runner by the access-gate fixture over TLS.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WT8bMasGPpqd8PDs7Fxs5m
…nd refuses a miscounted call

From the Copilot review of #244. A Host with a port now routes by its
first label alone; it already did whenever the name had a dot, which
every name the harness uses has. A call with only one of the
certificate and key files now exits with usage instead of serving plain
HTTP to a job that meant TLS.

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

From the maintainer's review of #244. The stand-in edits the runner's
CA store, /etc/hosts and a sysctl, which a self-hosted runner would
keep between jobs, so the job must stay on ubuntu-latest.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WT8bMasGPpqd8PDs7Fxs5m
@mmcky
mmcky force-pushed the feat/177-visibility-input branch from 397deaf to e6b04b7 Compare November 5, 2026 00:56
@mmcky
mmcky merged commit aed787e into main Nov 5, 2026
36 checks passed
@mmcky
mmcky deleted the feat/177-visibility-input branch November 5, 2026 01:03
mmcky added a commit that referenced this pull request Nov 5, 2026
Move [Unreleased] into a dated 0.14.0 section, carrying all of wave 1 (#246): #240, #241, #242, #244 and #245. Add an entry for Dependabot's quantecon-book-theme 0.22.1 bump in both images (#223), which had none. #240 changes every consumer's PR path, so the release is staged on the canary before v0 moves. This commit changes only CHANGELOG.md, and the harness has no @v0 workaround for this release to drop.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WT8bMbMmeUUEj8EjiweB6S
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: support public sites with an explicit visibility input

2 participants