Skip to content

fix(deploy): activate Workers that have no readiness URL #711

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
0froq wants to merge 3 commits into
base: main
Choose a base branch
from
+344 −115
Open

fix(deploy): activate Workers that have no readiness URL #711

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e2ddbaf
fix(deploy): activate Workers that have no readiness URL
0froq Nov 4, 2026
c69b5f3
style(docs): align Cloudflare deploy tables
0froq Nov 4, 2026
44d005a
fix(deploy): skip readiness only when a Worker has no HTTP routes
0froq Nov 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 9 additions & 9 deletions docs/integrations/cloudflare.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -133,14 +133,14 @@ Apps using email need `email.from` in `void.config.ts`. Void reviews the domain'

Set these CI secrets and variables as needed:

| Name | When needed |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| `CLOUDFLARE_API_TOKEN` | Required. Workers Scripts: Edit, read access to bound resources, and edit access to products Void provisions. |
| `CLOUDFLARE_ACCOUNT_ID` | When the token can access several accounts. |
| `DATABASE_URL` | PostgreSQL and MySQL provisioning and migrations. |
| `CLOUDFLARE_WORKERS_SUBDOMAIN` | When the Worker has no version preview URL. Use `my-team` or `my-team.workers.dev`. |
| `CF_ACCESS_CLIENT_ID`, `CF_ACCESS_CLIENT_SECRET` | When Cloudflare Access protects the readiness URL. |
| `CF_ACCESS_READINESS_ORIGIN` | When Access protects a route or Custom Domain and `workers_dev` is `false`. See [Cloudflare Access](#cloudflare-access). |
| Name | When needed |
| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CLOUDFLARE_API_TOKEN` | Required. Workers Scripts: Edit, read access to bound resources, and edit access to products Void provisions. |
| `CLOUDFLARE_ACCOUNT_ID` | When the token can access several accounts. |
| `DATABASE_URL` | PostgreSQL and MySQL provisioning and migrations. |
| `CLOUDFLARE_WORKERS_SUBDOMAIN` | When workers.dev is enabled and the version has no preview URL. Use `my-team` or `my-team.workers.dev`. An account subdomain does not create a readiness URL when `workers_dev` is false. |
| `CF_ACCESS_CLIENT_ID`, `CF_ACCESS_CLIENT_SECRET` | When Cloudflare Access protects the readiness URL. |
| `CF_ACCESS_READINESS_ORIGIN` | When Access protects a route or Custom Domain and `workers_dev` is `false`. See [Cloudflare Access](#cloudflare-access). |

For email, run `void email setup --platform cloudflare` locally, commit `void.lock.json`, and pass `--require-email` in CI. The token also needs Email Routing Edit and Email Sending Edit.

Expand Down Expand Up @@ -174,7 +174,7 @@ Set production server values with `void secret put <NAME>`. Void preserves exist

### Readiness and rollback

Void normally verifies an uploaded version before sending it traffic. If readiness or trigger updates fail, it restores the previous deployment. Finish or cancel any gradual rollout in Cloudflare before deploying through Void.
Void normally verifies an uploaded version before sending it traffic. A Worker with workers.dev turned off and no route or Custom Domain has no URL Void can check, so that deploy skips the readiness check and activates the uploaded version. If readiness or trigger updates fail, it restores the previous deployment. Finish or cancel any gradual rollout in Cloudflare before deploying through Void.

For an existing Durable Object Worker that Cloudflare cannot stage, review the changes and use:

Expand Down
20 changes: 10 additions & 10 deletions docs/reference/cli/deploy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -86,16 +86,16 @@ void deploy --platform cloudflare --require-email # fail instead of deploying

Void signs you in through your browser when needed and saves the selected account. In CI, set `CLOUDFLARE_API_TOKEN` and, if the token can access several accounts, `CLOUDFLARE_ACCOUNT_ID`.

| Option or setting | Cloudflare behavior |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
| `--dir`, `--spa` | Deploy static output through a small Worker and Workers Assets |
| `--skip-build` | Reuse existing static, SPA, or SSG output; unavailable for Worker apps |
| `--project` | Unavailable; the Worker and account come from `void.config.ts` and `void.lock.json` |
| Named environments | Unavailable; use the top-level `cloudflare` config |
| `CLOUDFLARE_WORKERS_SUBDOMAIN` | Needed in fresh CI when versions have no preview URL; cached locally after a deploy |
| `CF_ACCESS_READINESS_ORIGIN` | Lets Access credentials reach the readiness check on a route or Custom Domain, for example `https://app.example.com` |
| `--require-email` | Fail instead of deploying without email when the email step cannot run, as in CI |
| `DATABASE_URL` | Required in the deploy environment for PostgreSQL or MySQL provisioning and migrations |
| Option or setting | Cloudflare behavior |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `--dir`, `--spa` | Deploy static output through a small Worker and Workers Assets |
| `--skip-build` | Reuse existing static, SPA, or SSG output; unavailable for Worker apps |
| `--project` | Unavailable; the Worker and account come from `void.config.ts` and `void.lock.json` |
| Named environments | Unavailable; use the top-level `cloudflare` config |
| `CLOUDFLARE_WORKERS_SUBDOMAIN` | Needed in fresh CI when a workers.dev Worker has no preview URL; cached locally after a deploy. It does not apply when `workers_dev` is false |
| `CF_ACCESS_READINESS_ORIGIN` | Lets Access credentials reach the readiness check on a route or Custom Domain, for example `https://app.example.com` |
| `--require-email` | Fail instead of deploying without email when the email step cannot run, as in CI |
| `DATABASE_URL` | Required in the deploy environment for PostgreSQL or MySQL provisioning and migrations |

The token needs Workers Scripts: Edit, read access to bound resources, and edit access to products Void provisions. Commit `void.lock.json` after the first deploy before using other machines or CI.

Expand Down
Loading
Loading