Cloudflare Pages (abbreviated as Pages) has a concept of preview and production deployment. When coupled with Git, one branch can set to be the production branch, all others will be treated as preview branches automatically.

For each preview branch, e.g. pull request, an unique URL such as 9ad3c263.<project>.pages.dev is generated for previewing changes without effecting production.

This is our first actor on stage.

Website hosted on Pages is called "project".

The most convenient way to create a project is by connecting to a Github or Gitlab repository, such way Pages can track branches and build the website automatically if changes are made. Another two ways are using wrangler from command line or uploading assets manually through Cloudflare dashboard.

This is the second actor.

Pages dashboard shows that status of deployments, and also tracks all history deployments for rollback. Other settings like custom domain or changing the production branch can be found in different panels.

This is the third actor.

This blog is built using Lume which only runs on Deno. It is not something Cloudflare Pages supports that can build for me, so this ruled out the connecting-to-git-repo way to create project.

Also because this website uses Deno, installing wrangler through npm is not preferable. Besides, wrangler is so annoying to use to the degree that even Terraform seems likable¹.

Apparently the only way left for me was to upload assets manually. It was quick and easy, in no time project was ready and custom domain was assigned, life was happy. Time to integrate Github Action for building and publishing the website.

The final actor is here to start off the show.

Then the caveat hit me like so:

.                       The Caveat Train
.
.        Author             @@@""""""""""""""""""""*
.                         @" ___ ___________ __ __
.          O             II__[ ] | [ ] [ ] | __ _
.          |            {======|_|=========| __ _
.         / \          /oO--000'"`-OO---OO-'
.**********************************************************

All deployments created using wrangler from Github Action did not go production. Running the same wrangler deploy command on local machine still didn't update the production.

What?

More confusingly, the Github Action setup and wrangler command are copied from another website project which it is known to work just fine.

There wasn't any hidden CLI options and related environment variable had no effects, Google yielded nothing, Cloudflare forum had no similar reports and no issues on this problem were found. Hours passed YAML poked, it was getting more frustrating and out loud calling me to quite.

Suddenly, somehow, Google decided to sparkle some dust of its wisdom onto me, guiding me to the documentation of Cloudflare Pages with this warning:

If your project is a Direct Upload project, you will not have the option to configure production branch controls. To update your production branch, you will need to manually call the Update Project endpoint in the API...

Branch?

Upon closer observation, all production deployments, i.e. uploaded via the dashboard, had the main branch, whereas deployments made using wrangler had master branch, which matches the main branch of the git repo...

After changing the wrangler command to this, finally, following deployments were being pushed to production.

wrangler pages deploy --branch "main" ...

It turns out, Pages implicitly sets main as production branch if not specified, while wrangler uses the local branch it is running against by default. As mentioned above, all branches besides production are automatically preview branches. The mismatch is the root cause of this problem.

Wrangler has such a miserable CLI UX. It mentions nothing about branches, which could easily save hours of frustration.

Read the quote above from the official documentation. Nothing related to branch will be found in the miserable dashboard, not even a most slight hint because the project was created by manual uploading. Guess low power users don't need those information anyway. Adding insult to injury, in order to change the branch, a f* API call by hand is needed.

Congrats that Cloudflare is stepping into the grown up company world doing what other big techs do: inconsistent UI/UX. If there were even a single word mentioning the branches in the dashboard, hours of miserable life could be saved.

Of course the documentation has everything, but only devops those who have suffered enough can be granted to have a taste of such caged knowledge.

What a misery matryoshka as gift for everyday devops.

By the way, because Pages keeps a history of deployments, the misery journey is well preserved. Here's a screenshot of some failed deployments right before the problem was solved: