PageDeploy

Start the Project

In this example, we will build a small website and take it through the same workflow used throughout this guide.

The purpose is not to build a complicated website. The purpose is to understand what happens at each stage of a real project.

The project

Imagine that we are creating a simple website for a small business called Northstar Coffee.

Our initial website will contain only:

A header
A short introduction
A list of services
Contact information

Step 1 — Create a project folder

Create a folder on your computer for the new website.

northstar-coffee

Step 2 — Create the initial website

Inside the project folder, create the files needed for the first version of the website.

northstar-coffee/
├── index.html
└── css/
  └── style.css

Step 3 — Test the website locally

Open the project using your local development server and confirm that the website works before introducing Git.

Why test before Git?

Git records changes to your project. It does not determine whether your website actually works.

It is useful to make sure the starting version works before we begin tracking changes.

The starting point

At this moment, the project exists only on your computer.

Your computer
    │
    └── northstar-coffee
            │
            ├── index.html
            └── css/
                └── style.css

GitHub:       not connected

Cloudflare:   not connected

What we will build from here

We will gradually move this project through the complete development and deployment workflow.

Each stage will introduce one part of the process instead of doing everything at once.

Our first milestone

The immediate goal is to establish the project’s main branch.

Once that exists, we will create a feature branch and use it to make our first change.

Create the main Branch

The project currently exists only on your computer. Before we start developing features, we need amain branch that represents the stable starting point of the project.

Step 1 — Open the project in the terminal

Open your terminal inside the northstar-coffee project folder.

cd northstar-coffee

Step 2 — Initialize Git

Turn the project folder into a Git repository.

git init

Git now creates the hidden .git directory and begins tracking the project.

Step 3 — Check the repository

git status

You should see the files in the project listed as untracked files.

Step 4 — Check your ignore rules

Before staging the project, make sure your .gitignore is configured if the project contains files that should not be committed, such as dependencies or environment files.

For this simple static example there may be nothing additional to ignore, but the same habit applies to real projects.

Step 5 — Stage the initial files

git add .

The files are now staged and ready to be included in the first commit.

Step 6 — Create the first commit

git commit -m “Initial project”

This creates the first snapshot of the project.

Step 7 — Make sure the branch is called main

Rename the current branch to main.

git branch -M main

Step 8 — Verify the branch

git branch

The output should show:

* main

Why is main important?

In our workflow, main represents the stable production line of the project.

We will not normally build new features directly on main.

Instead, we will create feature branches from main and merge completed work back into it.

The project now looks like this

northstar-coffee
      │
      └── Git repository
              │
              └── main
                   │
                   └── Initial project

What has not happened yet?

The repository is still only on your computer.

We have not connected it to GitHub yet.

Your computer
    │
    └── Git repository
            │
            └── main

GitHub
    │
    └── Not connected yet

Cloudflare Pages
    │
    └── Not connected yet

The important milestone

We now have a local Git repository with a committed main branch.

The next step will be to create the corresponding repository on GitHub and connect the two.

Create a Feature Branch

The main branch now contains our stable starting version.

Instead of changing main directly, we will create a separate branch for our next piece of work.

The feature we are going to build

Let’s say the client has requested a new menu section for the Northstar Coffee website.

We will build that feature on its own branch.

Step 1 — Make sure you are on main

git switch main

In a real project, make sure your local main branch is up to date before creating new work. Once GitHub is connected, this can be done with git pull origin main.

Verify the current branch:

git branch

You should see:

* main

Step 2 — Create the feature branch

Create a new branch called:

feature/menu

Use:

git switch -c feature/menu

This command does two things:

Creates the feature/menu branch.
Immediately switches you to that branch.

Step 3 — Verify the branch

git branch

You should now see something similar to:

  main
* feature/menu

The * shows the branch you are currently working on.

What just happened?

Nothing has been changed in the website yet.

We simply created a safe workspace where the new feature can be developed.

Why not build directly on main?

The main branch represents the stable version of the project.

If we experiment directly on main and something goes wrong, the stable version can be affected.

A feature branch keeps the new work separate until it has been tested and reviewed.

Our branch structure

main
│
└── feature/menu
    │
    └── Menu feature development

Important

From this point onward, make the menu changes while you are on feature/menu.

Do not switch back to main until we specifically need to.

What comes next?

We now have a feature branch ready for development.

The next step is to actually build the menu feature and test it locally.

Build the Feature

We are now working on the feature/menu branch.

This is where normal development happens: edit the files, run the website locally, and test the feature.

Step 1 — Confirm the current branch

git branch

Make sure the feature branch is active:

  main
* feature/menu

Step 2 — Add the menu section

Open index.html and add a simple menu section to the website.

For example:

<section class="menu">

<h2>Our Menu</h2>

<ul>
  <li>Espresso — $3</li>
  <li>Cappuccino — $4</li>
  <li>Cold Brew — $5</li>
</ul>

</section>

Step 3 — Save the changes

Save the modified files.

Git will now recognize that the working directory is different from the last commit.

Step 4 — Check Git status

git status

You should see the modified file listed.

modified: index.html

What Git is telling you

Git has detected a change, but the change has not been committed yet.

The change exists only in your working directory at this point.

Step 5 — Run the website locally

Start your local development server and open the website in your browser.

Confirm that the new menu section appears correctly.

Step 6 — Make adjustments if necessary

If the menu does not look correct, continue editing the files and test again.

You can make as many local changes as necessary before creating the commit.

The important idea

feature/menu
│
├── Edit files
│
├── Run locally
│
├── Test
│
└── Fix if necessary

Do not commit yet

At this stage, we are only developing and testing the feature.

We will inspect the final changes and create the commit in the next step.

What comes next?

Once the feature works locally, we need to record the changes in Git with a commit.

Commit the Feature

The menu feature has been built and tested locally on the feature/menu branch.

We will now create a Git commit that records this version of the feature.

Step 1 — Check the current branch

git branch

Confirm that you are still on:

* feature/menu

Check before committing

Make sure you are committing the feature on feature/menu, not directly on main.

Step 2 — Inspect the changes

git status

Git should show the files that have changed.

You can also inspect the actual line-by-line changes:

git diff

Good habit

Review git diff before staging. It helps catch accidental edits, debugging code, or unrelated changes before they become part of the commit.

Step 3 — Stage the changes

For our small example, stage the project changes:

git add .

The changes are now in Git’s staging area.

Step 4 — Verify the staged changes

git status

The modified files should now appear under Changes to be committed.

You can inspect exactly what is staged with:

git diff –staged

Step 5 — Create the commit

git commit -m “Add coffee menu section”

Git creates a new commit on the feature/menu branch.

Step 6 — Check the result

git status

If everything was committed successfully, Git should report that the working tree is clean.

View the commit

git log –oneline

You should now see the menu commit above the initial project commit.

a1b2c3d Add coffee menu section
7e8f9a0 Initial project

The commit IDs will be different

Values such as a1b2c3d are example shortened commit IDs.

Git will generate different commit IDs in your repository.

Where does the commit exist?

At this point, the new commit still exists only in your local Git repository.

Your computer

main
│
└── Initial project
 │
 └── feature/menu
        │
        └── Add coffee menu section


GitHub
│
└── Not connected yet

Commit does not mean push

git commit records the change in your local Git repository.

It does not automatically send the commit to GitHub.

What comes next?

We now have something important to address.

Our local project has Git history, but we still have no GitHub repository connected to it.

In the next stage, we will create the GitHub repository, connect it as the remote, and push our branches.

Create the GitHub Repository

Our project now has Git history, but the repository exists only on the local computer.

The next step is to create a repository on GitHub and connect our local repository to it.

Step 1 — Open GitHub

Step 2 — Name the repository

For this example, use:

northstar-coffee

Using the same name as the local project makes the repository easier to recognize.

Step 3 — Choose repository visibility

GitHub allows you to create the repository as either public or private.

For this example, either is technically possible. Choose the visibility appropriate for your project.

Do not initialize the repository

Because we already have a local Git repository with a commit, create the GitHub repository without adding another initial README, .gitignore, or license.

This keeps the Git history simple when we connect the two repositories.

Step 4 — Create the repository

Create the GitHub repository.

GitHub will then provide the repository address.

https://github.com/YOUR-USERNAME/northstar-coffee.git

Replace YOUR-USERNAME with your GitHub username.

Step 5 — Connect the local repository

Return to the terminal inside the local project.

Add the GitHub repository as a remote named origin:

git remote add origin https://github.com/YOUR-USERNAME/northstar-coffee.git

Step 6 — Verify the remote

git remote -v

You should see the GitHub repository listed for both fetching and pushing.

origin  https://github.com/YOUR-USERNAME/northstar-coffee.git (fetch)
origin  https://github.com/YOUR-USERNAME/northstar-coffee.git (push)

What is origin?

origin is simply the conventional name Git gives to the remote repository.

It is not a special server. It is a short name that points to our GitHub repository.

Step 7 — Push main to GitHub

Our local main branch contains the initial project commit.

Push it to GitHub:

git push -u origin main

The -u option establishes the relationship between the local main branch and the remote origin/main branch.

Step 8 — Push the feature branch

Our menu feature is also committed locally on feature/menu.

Push that branch to GitHub as well:

git push -u origin feature/menu

What GitHub now contains

GitHub
│
└── northstar-coffee
 │
 ├── main
 │    └── Initial project
 │
 └── feature/menu
      └── Add coffee menu section

Local and remote repositories

Your local repository and GitHub repository now contain the same branches and commits.

From this point forward, GitHub becomes the shared remote repository for the project.

A very important distinction

git commit
↓
Records changes locally

git push
↓
Sends commits to GitHub

A commit does not automatically appear on GitHub. The commit must be pushed to the remote repository.

What comes next?

We now have our feature branch on GitHub.

Cloudflare Pages can use that branch to create a preview deployment.

That will allow us to test the feature online before merging it into main.

Deploy the Feature Branch to Preview

Our feature/menu branch is now on GitHub.

Cloudflare Pages can use that branch to create a preview deployment without changing the production website.

Why use a preview?

A preview gives you an online version of your feature that can be tested before the feature is merged into main.

Production is protected

Our production branch is main.

The menu feature exists on feature/menu, so its deployment is treated as a preview rather than production.

Step 1 — Open the Cloudflare Pages project

Open your Cloudflare dashboard and select the Pages project connected to the northstar-coffee GitHub repository.

Step 2 — Find the deployment

With the GitHub integration and preview deployments configured, Cloudflare Pages can create a preview deployment for the new branch.

Open the project’s deployment area and find the deployment associated with:

feature/menu

Step 3 — Open the preview URL

Cloudflare provides a unique URL for the preview deployment.

Open that URL in your browser.

Step 4 — Test the menu

Check that the new menu section appears correctly.

Test the page as if you were a visitor:

Check the layout.
Check the menu content.
Check links and buttons.
Check the page on different screen sizes.

What happens if something is wrong?

Go back to your local project, make the required changes, test them locally, commit them, and push the new commit to the same feature branch.

git add .
git commit -m "Fix menu layout"
git push

Cloudflare can then create an updated preview from the new commit.

Preview is part of the development cycle

You can repeat this cycle as many times as necessary:

Edit → Commit → Push → Preview → Test

Preview versus production

Feature branch	main branch
Development work	Stable production work
Preview deployment	Production deployment
Safe place to test changes	Website visitors use this version

The workflow now

feature/menu
│
│ push
▼
GitHub
│
▼
Cloudflare Preview
│
▼
Test the feature
│
├── Fix → commit → push → test again
│
└── Ready
       ↓
   Pull Request

Do not merge yet

The purpose of this stage is to test the feature in its preview environment.

We will create the Pull Request only after the feature has been verified.

What comes next?

Once the preview has been tested successfully, we can ask GitHub to merge the feature into main through a Pull Request.

Create a Pull Request

The menu feature has been built, committed, pushed to GitHub, and tested through its Cloudflare preview.

It is now ready to be proposed for inclusion in the main branch.

What is the Pull Request doing?

The Pull Request asks:

Can we merge
feature/menu
into
main?

GitHub will show the changes between the two branches so they can be reviewed before the merge.

Step 1 — Open the GitHub repository

Open the northstar-coffee repository on GitHub.

Step 2 — Start the Pull Request

GitHub may show a prompt to create a Pull Request after you push the feature branch.

You can also open the repository’s Pull Requests area and create a new Pull Request manually.

Step 3 — Check the branches

Before creating the Pull Request, make sure the branch direction is:

base:    main
compare: feature/menu

Check base and compare carefully

base is the branch receiving the changes.

compare is the branch containing the changes.

For our workflow, the feature branch should be compared against main.

Step 4 — Add a clear title

Give the Pull Request a short description of what the feature does.

Add coffee menu section

Step 5 — Describe the change

Explain what was changed and, when useful, how it was tested.

## Changes

- Added the coffee menu section
- Added three menu items
- Tested the layout locally
- Tested the Cloudflare preview

Step 6 — Review the changed files

Before creating the Pull Request, review the files GitHub says will be changed.

Make sure only the intended feature changes are included.

Step 7 — Create the Pull Request

Create the Pull Request once the title, description, branches, and changed files are correct.

The feature is not merged yet

Creating a Pull Request does not immediately change the main branch.

The Pull Request creates a review point between the feature branch and main.

The workflow now

feature/menu
│
├── Build
├── Commit
├── Push
│
▼
Cloudflare Preview
│
├── Test
│
▼
GitHub Pull Request
│
├── base: main
└── compare: feature/menu
       │
       ▼
     Review
       │
       ▼
     Merge

Do not merge yet

We will treat the Pull Request as a separate review step.

The next section will cover reviewing and merging the Pull Request into main.

What comes next?

The Pull Request now represents the proposed change. The next step is to review it and merge it into main.

Review and Merge the Pull Request

The Pull Request now contains the proposed menu feature. Before merging it, review the changes and confirm that the feature is ready to become part of main.

Step 1 — Review the Pull Request

Open the Pull Request on GitHub and review the files and changes included in it.

Check that the changes match the feature you intended to build.

Step 2 — Check the deployment

Check the status of the Cloudflare preview deployment associated with the feature branch.

The preview should have completed successfully and the menu should have been tested.

Review before merge

Correct branch direction
Expected files changed
Preview deployment successful
Feature tested

Step 3 — Merge the Pull Request

Once the Pull Request is ready, use GitHub’s merge action to merge it into main.

The important relationship is:

feature/menu
↓
Pull Request
↓
main

Step 4 — Confirm the merge

After the merge, GitHub will show that the Pull Request has been merged.

The menu feature is now part of the main branch.

Step 5 — Understand what changed

Before the merge, the branches looked conceptually like this:

main
│
└── Initial project

feature/menu
│
└── Add coffee menu section

After the merge:

main
│
├── Initial project
│
└── Add coffee menu section

The feature branch is no longer the production line

The feature has now become part of main.

Cloudflare Pages can detect the new commit on the production branch and begin a production deployment.

Step 6 — Update your local repository

The merge happened on GitHub, so your local main branch may not yet contain the merge.

Switch to main:

git switch main

Then download the latest changes from GitHub:

git pull origin main

Verify the result

git log –oneline

The menu feature should now appear in the history of your local main branch.

What happened to feature/menu?

The branch may still exist after the merge.

If it is no longer needed, GitHub allows you to delete the feature branch after the Pull Request has been merged.

A useful distinction

Merging the Pull Request combines the feature into main.

Deleting feature/menu afterward does not remove the merged feature from main.

The complete development cycle

main
│
└── feature/menu
    │
    ├── Build
    ├── Commit
    ├── Push
    │
    ▼
Cloudflare Preview
    │
    ├── Test
    │
    ▼
Pull Request
    │
    ├── Review
    │
    ▼
  Merge
    │
    ▼
  main
    │
    ▼
Production deployment

What comes next?

The feature is now merged into main.

The next step is to see what happens when Cloudflare Pages detects that production branch change and deploys the updated website.

Deploy to Production

The menu feature has now been merged into the main branch.

Because Cloudflare Pages is configured to use main as the production branch, the merge creates a new production-branch commit that can trigger the production deployment process.

Step 1 — main changes on GitHub

The merge adds the menu feature to the history of the main branch.

main
│
├── Initial project
│
└── Add coffee menu section

Step 2 — Cloudflare detects the change

Cloudflare Pages watches the connected GitHub repository.

When a new commit reaches the configured production branch, Cloudflare can start a new production deployment.

Step 3 — Cloudflare builds the project

Cloudflare runs the project’s configured build process.

If the build succeeds, Cloudflare creates a new deployment from the latest version of main.

Build failure

If the build fails, the deployment does not become the new production version.

The deployment logs can be used to identify and fix the problem.

Step 4 — Production deployment completes

After a successful deployment, the new version of the website becomes the production version.

The menu feature is now available through the production website.

Step 5 — Verify the production website

Open the production URL and confirm that the menu appears correctly. A successful deployment only means the deployment completed; you should still test the actual production website.

https://pagedeploy.com

In a real project, replace this example with your actual production domain.

The complete journey

Local project
    │
    ▼
Git
    │
    ▼
feature/menu
    │
    ▼
GitHub
    │
    ▼
Cloudflare Preview
    │
    ▼
Test
    │
    ▼
Pull Request
    │
    ▼
Merge into main
    │
    ▼
Cloudflare Production
    │
    ▼
Custom Domain
    │
    ▼
Website visitors

The complete mental model

Git tracks the project’s history.

GitHub stores and shares the repository.

Feature branches isolate new development.

Pull Requests provide the review and merge point.

Cloudflare Preview lets you test branch changes online.

Cloudflare Pages deploys the production branch.

Custom DNS connects the domain to the deployed website.

Chapter 13 complete

You have now followed one feature from the first local change all the way to the production website.

The same cycle can be repeated whenever a new feature needs to be developed.

main
↓
feature branch
↓
develop
↓
commit
↓
push
↓
preview
↓
test
↓
Pull Request
↓
merge
↓
main
↓
production