Deploy via GitHub Actions

Notice

Currently only supports Worker and Pages deployment. If you encounter any issues, please report them via GitHub Issues. Thank you.

The worker.dev domain is inaccessible in China, please use a custom domain

Deployment Steps

Fork Repository and Enable Actions

• Fork this repository on GitHub
• Open the Actions page of the repository
• Find Deploy Backend and click enable workflow to enable the workflow
• If you need separate frontend and backend deployment that talks to Worker directly, find Deploy Frontend and click enable workflow to enable the workflow
• If you need Pages deployment with Page Functions forwarding backend requests, find Deploy Frontend with page function and click enable workflow to enable the workflow

Configure Secrets

Then go to the repository page Settings -> Secrets and variables -> Actions -> Repository secrets, and add the following secrets:

• Common secrets

  Name	Description
  CLOUDFLARE_ACCOUNT_ID	Cloudflare Account ID, Reference Documentation
  CLOUDFLARE_API_TOKEN	Cloudflare API Token, Reference Documentation

• Worker backend secrets

  Name	Description
  BACKEND_TOML	Backend configuration file, see here
  DEBUG_MODE	(Optional) Whether to enable debug mode, set to true to enable. By default, worker deployment logs are not output to GitHub Actions page, enabling this will output them
  BACKEND_USE_MAIL_WASM_PARSER	(Optional) Whether to use WASM to parse emails, set to true to enable. For features, refer to Configure Worker to use WASM Email Parser
  USE_WORKER_ASSETS	(Optional) Deploy Worker with frontend assets, set to true to enable

• Pages frontend secrets

  Notice

  If you choose to deploy Worker with frontend assets, these secrets are not required

  Name	Description
  FRONTEND_ENV	Frontend configuration file used by the Deploy Frontend workflow. Copy the content from frontend/.env.example, and modify it according to this guide. For separate frontend/backend deployment that talks to Worker directly, VITE_API_BASE should be the backend Worker API root URL, must start with https://, and must not include a trailing /. When this address is configured incorrectly, common symptoms are the map error or 405 API responses
  FRONTEND_NAME	The project name you created in Cloudflare Pages, can be created via UI or Command Line
  FRONTEND_BRANCH	(Optional) Branch for pages deployment, can be left unconfigured, defaults to production
  PAGE_TOML	(Optional) Used only by the Deploy Frontend with page function workflow. Required when using page functions to forward backend requests. Please copy the content from pages/wrangler.toml and modify the service field to your worker backend name according to actual situation. This workflow builds the frontend in Pages mode and uses same-origin requests, so it does not read FRONTEND_ENV
  TG_FRONTEND_NAME	(Optional) The project name you created in Cloudflare Pages, same as FRONTEND_NAME. Fill this in if you need Telegram Mini App functionality

Deploy

• Open the Actions page of the repository
• Find Deploy Backend and click Run workflow to select a branch and deploy manually
• If you need separate frontend and backend deployment that talks to Worker directly, find Deploy Frontend and click Run workflow to select a branch and deploy manually
• If you need Pages deployment with Page Functions forwarding backend requests, find Deploy Frontend with page function and click Run workflow to deploy manually

Auto-Update with Page Functions Forwarding

If you want to use Upstream Sync for automatic updates and also let Pages forward backend requests through Page Functions, use the Deploy Frontend with page function workflow instead of Deploy Frontend.

• Enable Upstream Sync, Deploy Backend, and Deploy Frontend with page function
• Configure the PAGE_TOML repository secret by copying the content of pages/wrangler.toml
• Change the service field in PAGE_TOML to your Worker backend name
• This workflow runs pnpm build:pages, uses same-origin frontend requests, and does not read FRONTEND_ENV
• After each completed Upstream Sync, Deploy Frontend with page function deploys the frontend automatically when PAGE_TOML is configured

How to Configure Auto-Update

1. Open the Actions page of the repository, find Upstream Sync, and click enable workflow to enable the workflow
2. If Upstream Sync fails, go to the repository homepage and click Sync to synchronize manually