Cloudflare Pages

What it does

• Pull at build: the project's build command runs stoaken export first, so every deployment ships the live release's tokens.
• Push on publish: a standard Stoaken webhook calls a Pages Deploy Hook, a URL that starts a new build on each POST and needs no other authorisation (docs), so a published release redeploys the site. See /docs/webhooks.
• Workers too: a Worker that builds with Workers Builds has its own Deploy Hooks, which work the same way (docs).

Before you start

• A Stoaken API key and a stoaken.config.json with exports (see /docs/cli).
• A Pages project connected to a Git repository. A Direct Upload project can't switch to Git later and has no builds to start (docs), so make a Git-connected project.
• Brand Admin in Stoaken, on the Team plan, for the webhook part.

Setup

1. In Workers & Pages, open the project, then Settings > Environment variables. Add STOAKEN_TOKEN (your API key) for Production and Preview, encrypted.
2. In the project's build configuration (Settings > Builds), put the export in front of the build command: npx --yes stoaken@latest export && npm run build. The same settings as an API body (template: cloudflarePagesBuildConfig() in src/lib/integrations/pipelines.ts, for PATCH /accounts/{account_id}/pages/projects/{project_name}):

{
  "build_config": {
    "build_command": "npx --yes stoaken@latest export && npm run build"
  }
}

3. Under Settings > Builds, choose Add deploy hook, name it (for example stoaken), pick the branch to build, and copy the URL.
4. In Stoaken, choose Add a webhook, set Send as to Stoaken event, paste the hook URL as the address, and pick Release published.

Configuration

• The CLI needs Node.js 20 or later. The v3 build image runs 22. On an older image, set NODE_VERSION or add an .nvmrc (docs).
• To export only on some branches, branch on CF_PAGES_BRANCH in the build command (docs).
• Workers Builds: put the same export in front of the Worker's Build command under Settings > Build, and leave the deploy command as npx wrangler deploy. Add STOAKEN_TOKEN under the build's Build variables and secrets, not the Worker's runtime variables (docs). Its Deploy Hook is under Settings > Builds > Deploy Hooks.
• If you also commit token files, add npx stoaken export --check to your Git provider's CI (see the GitHub, GitLab or Bitbucket guide) rather than to the Cloudflare build.

Try it

1. Send test should get a 2xx from Cloudflare and start a deployment whose Source shows the Deploy Hook. Cloudflare doesn't read the body, so a test builds for real.
2. The deployment's build log shows the stoaken export lines.

Troubleshooting

• Build fails at export with 401: STOAKEN_TOKEN is missing for that environment (Production or Preview), or the key was revoked.
• No Add deploy hook option: the project is Direct Upload. Make a Git-connected project.
• Workers Builds answers 429: hooks are limited to 10 builds a minute per Worker and 100 per account. Stoaken retries later.
• Fewer Workers builds than releases: a hook fired again before the first build starts doesn't queue another one. Cloudflare answers with already_exists: true.

Limits

• A Deploy Hook redeploys one branch. It doesn't change your repository.
• Anyone with the hook URL can start a build. Brand Admins can see it in Stoaken, so delete the hook and make a new one if it leaks.
• Pages keeps the build command in the project, not the repository, so the template is a settings body, not a file to commit.