publish to Cloudflare Pages

This guide will show you how to setup a project to build and deploy to Cloudflare Pages.

The code repository

We start with creating a code repository in github-provisioning. Make sure to set auto_init=true and to provision a workflow to publish either a Javascript or Python project. Also include the semgrep workflow.

Once done, merge your PR and wait for it to finish creating your repository.

You now need to go back and add a resource that manages branch protection, to make sure nothing lands in main without having been validated through a PR-review process.

Please consult the Terraform provider documentation on how to do this.

It basically comes down to this:

resource "github_branch_protection_v3" "my_awesome_project" {
  repository             = github_repository.my_awesome_project.name
  branch                 = "main"
  enforce_admins         = true
  require_signed_commits = false
  required_status_checks {
    strict = false
  }
  required_pull_request_reviews {
    required_approving_review_count = 1
  }
}

Merge this change and your ready to push code.

The Pages project

Next we need a Cloudflare Pages project. This is easily done in cloudflare-provisioning. Create a PR and you’ll be ready in minutes. You will find the necessary Terraform resources described in the relevant README section.

Here you can also choose to define additional Access Applications to block access to your production deployment. For example, if your project’s production website is to remain internal and accessible only to visitors with a valid Okta session.

Using it

Now that we have both the code repository and a Pages project we are ready to ship.

Start with a git commit of your project’s code to a new branch.

Our Javascript GitHub workflow will execute regular npm commands so make sure your packages.json defines these as specified in the workflow.

You can make the Javascript build-stage behave different depending on environment, by setting repository secrets. Any secret with prefix NEXT_ will be made available as environment variable.

Are you building a Javascript website? Make sure to place your artifacts in ./build/!

Building a NextJS project? Make sure to have these in your next.config.js:

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export',
  distDir: 'build',
}

The Python workflow expects a Pipfile environment as defined here.

Are you building a Python website? Make sure to include a Makefile that builds your HTML in ./build/html/!

Tools like Sphinx ship with a Makefile, an example can be found in this repository.

Create a Pull Request to merge your work into your project’s main branch. This will execute the publish workflow and will upload your artifacts to Pages. A preview link will be shared as PR comment, often looking like https://pr-1337.my-awesome-project.pages.dev. This PR preview is accessible to anyone with a valid Okta role.

Once satisfied, merging the branch will create a new build, this time deploying to production from where it will be accessible to the world.