# 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](https://github.com/TinkaTech/github-provisioning).
Make sure to set `auto_init=true` and to provision a [workflow](https://github.com/TinkaTech/github-provisioning/blob/master/workflows/github-workflows/) to publish either a Javascript or Python project.
Also include the [semgrep](https://github.com/TinkaTech/github-provisioning/blob/master/workflows/github-workflows/semgrep/workflow.yml) 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](https://registry.terraform.io/providers/integrations/github/latest/docs/resources/branch_protection_v3) on how to do this.

It basically comes down to this:
```hcl
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](https://github.com/TinkaTech/cloudflare-provisioning).
Create a PR and you'll be ready in minutes. You will find the necessary Terraform resources described in the relevant [README](https://github.com/TinkaTech/cloudflare-provisioning#cloudflare-pages) 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](https://github.com/TinkaTech/github-provisioning/blob/master/workflows/github-workflows/publish-js-to-cloudflare/workflow.yml).

> 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](https://github.com/TinkaTech/github-provisioning/blob/master/workflows/github-workflows/publish-js-to-cloudflare/workflow.yml#L40) 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](https://nextjs.org/docs/pages/api-reference/next-config-js/distDir) in your `next.config.js`:
> ```js
> /** @type {import('next').NextConfig} */
> const nextConfig = {
>   output: 'export',
>   distDir: 'build',
> }
> ```

The Python workflow expects a `Pipfile` environment as defined [here](https://github.com/TinkaTech/github-provisioning/blob/master/workflows/github-workflows/publish-python-to-cloudflare/workflow.yml).

> 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](https://github.com/TinkaTech/developers.tinka.tools/blob/main/Makefile).

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_.