How to create staging environment on Cloudflare Pages

As far as I know, Cloudflare does not officially provide documents to set up staging environments on Cloudflare Pages.
I raised a feature request to allow us creating staging environments, and then I got an advise how to create staging environments.

Premises

When you push or merge changes to the staging branch on GitHub, the content of the staging branch will be deployed and the deployment can be accessible from stg.example.com.
The deployment of the main branch can be accessible from example.com as well.

• Project name of Cloudflare Pages: example-prj
• Name of the Git branch corresponding to the staging environment: staging
• Domain name for staging environment: stg.example.com (You can also associate different apex domain like example-stg.com.)
• Name of the Git branch for production environment: main
• Domain name for production environment: example.com

1. Create staging branch on GitHub

Create it as usual.

2. Add stg.example.com to Custom Domains of Cloudflare Pages

You can see Custom Domains tab on the Cloudflare Pages dashboard.
Add stg.example.com from the tab.

3. Fix DNS so that stg.example.com points the deployment for staging branch

By adding the custom domain to Cloudflare Pages, the new CNAME record stg.example.com which points example-prj.pages.dev is automatically added to your DNS.

Modify the DNS record value so that it points staging.example-prj.pages.dev.

Note that you need to enable Cloudflare CDN (orange-cloud) for stg.example.com. If you disable Cloudflare CDN (gray-cloud), stg.example.com does not point staging deployment properly.

(Therefore, I guess you cannot associate domain with staging deployment if you use a DNS provider other than Cloudflare. See next section for possible workaround.)

Why this works?

Actually, each deployments of the non-production branches are accessible with BRANCH_NAME.example-prj.pages.dev. We just associated the custom domain with it.

As I mentioned, if you use a DNS other than Cloudflare, I guess you cannot associate custom domain with the staging deployment. You can use staging.example-prj.pages.dev as the staging environment.

Comments

[Ricardo]

Hi, how would you share environment variables between Production and Staging?
That's something I haven't been able to solve, since Cloudflare pages only has the option to set production or preview env variables.

[Ben Racicot]

Can you add them into your deployment command?
Did you solve this?

[Jumpei Ogawa]

Hi Ricardo,
Sorry for the late reply. (The notification email is not sent to me for some reason.)

The REST API might help you to set the same environment variables between production and staging automatically.
api.cloudflare.com/#pages-project-...

However, I usually set only one environment variable SERVER_ENV=production or SERVER_ENV=staging and switch other values in the application like this:

if (process.env.SERVER_ENV === "production") {
  domain = "example.com";
  noindex = false;
  // ...
} else if (process.env.SERVER_ENV === "staging") {
  domain = "example.net";
  noindex = true;
  // ...
}

I recommend to reduce the number of environment variables so that you don't have to set the same environment variables manually if that works in your project.

[Ben Racicot]

Thanks Jumpei! Looks like there's now an official page for this.

[Jumpei Ogawa]

Hi Ben,
Sorry for the late reply. (The notification email is not sent to me for some reason.)

Thanks for letting me know, but I couldn't find the official document for creating staging environment on Cloudflare Pages. Where is the official document?