Development Branch Setup Guide

This guide explains how to use Cloudflare Pages' built-in branch preview system for the TxCR Documentation site.

Overview

Cloudflare Pages automatically creates preview deployments for all branches:

• Production (master branch): https://docs.txcr.dev
• Preview (dev branch): https://dev.{your-project}.pages.dev
• Preview (other branches): https://{branch-name}.{your-project}.pages.dev

Getting Started

1. Configure Cloudflare Pages Project

You only need one Cloudflare Pages project. Cloudflare automatically handles preview deployments:

1. Go to your Cloudflare dashboard → Pages
2. Your existing project is already set up for production (master branch)
3. Cloudflare will automatically create preview URLs for other branches
4. Optional: Set up a custom domain for production (e.g., docs.txcr.dev)
5. Optional: Set up custom domains for specific preview branches

Adding Custom Domains to Preview Branches

You can add custom domains to specific preview branches:

1. In Cloudflare Pages, go to your project → Custom domains
2. Click Set up a custom domain
3. Enter your custom domain (e.g., dev-docs.txcr.dev or preview.txcr.dev)
4. In the Branch dropdown, select the specific branch (e.g., dev)
5. Add the required DNS records in your domain's DNS settings

This way you can have:

• Production: docs.txcr.dev (master branch)
• Dev Preview: dev-docs.txcr.dev (dev branch)
• Other branches: {branch}.{project}.pages.dev (auto-generated)

2. Configure GitLab Variables

In your GitLab project settings (Settings > CI/CD > Variables), you only need:

Variable	Value	Description
CF_API_TOKEN	Your Cloudflare API token	Required for Wrangler deployments
CF_PAGES_PROJECT	Your project name	Single Cloudflare Pages project

3. Create the Dev Branch

git checkout -b dev
git push -u origin dev

Development Workflow

Working on New Features

1. Start from dev branch:

   git checkout dev
   git pull origin dev

2. Create feature branch (optional but recommended):

   git checkout -b feature/my-new-feature

3. Make your changes and test locally:

   # Regular local development
   yarn start
   
   # Or test with dev environment simulation
   yarn dev:preview

4. Commit and push to dev:

   git add .
   git commit -m "Add new feature"
   git checkout dev
   git merge feature/my-new-feature
   git push origin dev

5. Review changes on preview site:

   • Visit the preview URL shown in the GitLab CI/CD job output
   • Or go to https://dev.{your-project}.pages.dev
   • You can find the exact URL in your Cloudflare Pages dashboard

6. Deploy to production when ready:

   git checkout master
   git merge dev
   git push origin master

Local Development Commands

• yarn start - Regular development server
• yarn dev:preview - Development server with dev branch simulation
• yarn build - Build the site locally
• yarn serve - Serve built site locally

Visual Indicators

Development Environment Features

• Title: Shows "(DEV)" suffix in the navbar title
• Dev Indicator: Orange "🚧 DEV PREVIEW" badge in the navbar
• Styling: Pulsing animation to make it clear this is a preview

Environment Detection

The site automatically detects the environment based on:

• CI_COMMIT_BRANCH environment variable (in CI/CD)
• DOCUSAURUS_URL environment variable
• Build-time configuration

Cloudflare Pages Configuration

Single Project Setup

• Project: Uses $CF_PAGES_PROJECT variable
• Production Branch: master → https://docs.txcr.dev (custom domain)
• Dev Preview: dev → https://dev-docs.txcr.dev (optional custom domain)
• Other Preview Branches: https://{branch}.{project}.pages.dev (auto-generated)
• Build Command: yarn build
• Output Directory: build

Custom Domains for Previews

Cloudflare Pages allows you to set custom domains for specific branches:

Steps to add a custom domain to the dev branch:

1. Go to Cloudflare dashboard → Pages → Your Project
2. Click Custom domains tab
3. Click Set up a custom domain
4. Enter domain: dev-docs.txcr.dev
5. Select branch: dev (from dropdown) ⚠️ This is the key step!
6. Add DNS record in Cloudflare DNS:
   • Type: CNAME
   • Name: dev-docs (or your subdomain)
   • Target: {your-project}.pages.dev
   • Proxy status: Proxied (orange cloud)

How it works:

• Each custom domain is explicitly tied to a specific branch in the Cloudflare UI
• When you add the domain, you must select which branch it serves
• The same DNS record can point to different content based on which branch you selected
• You can see the branch assignment in the Custom domains list
• Example:
  • docs.txcr.dev → assigned to master branch
  • dev-docs.txcr.dev → assigned to dev branch
  • Both use the same project, but serve different branch content

Result:

• Master branch: docs.txcr.dev
• Dev branch: dev-docs.txcr.dev
• Feature branches: feature-xyz.{project}.pages.dev

How Preview Deployments Work

1. Automatic Creation: Cloudflare automatically creates a preview URL for each branch
2. URL Pattern: https://{branch-name}.{project-name}.pages.dev
3. Branch Sanitization: Special characters in branch names are converted to hyphens
4. No Extra Setup: No need for multiple projects or custom domains for previews

CI/CD Pipeline

The GitLab CI pipeline now includes:

Stages

1. Test: Runs on both master and dev branches
2. Deploy: Separate jobs for production and development

Jobs

• test: Validates builds for all branches
• deploy_production: Deploys master branch to production
• deploy_preview: Deploys dev and other branches to preview URLs

Finding Your Preview URL

After pushing to a branch, you can find the preview URL in several ways:

1. GitLab CI/CD Output: Check the job log for the deployment URL
2. Cloudflare Dashboard: Go to Pages → Your Project → Deployments
3. GitLab Environment: Check Deployments → Environments in your GitLab project
4. Direct URL: https://{branch-name}.{project-name}.pages.dev

Verifying Custom Domain → Branch Mapping

To confirm which branch a custom domain points to:

1. Go to Cloudflare Pages → Your Project → Custom domains
2. You'll see a table showing:

   Domain                  Branch    Status
   docs.txcr.dev          master    Active
   dev-docs.txcr.dev      dev       Active
3. The Branch column explicitly shows which branch each domain serves
4. Click the domain to see details or change the branch assignment

Troubleshooting

Common Issues

1. Environment variables not set: Ensure CF_API_TOKEN and CF_PAGES_PROJECT are configured in GitLab
2. Preview URL not working: Check Cloudflare Pages dashboard for deployment status
3. Build failures: Check the CI/CD logs for specific error messages
4. Wrong preview URL: Branch names with special characters are converted to hyphens

Useful Commands

# Check current branch
git branch

# Switch to dev branch
git checkout dev

# View GitLab CI pipeline status
# (Check in GitLab web interface)

# Test local build
yarn build

# Clean build cache if needed
yarn clear

Best Practices

1. Always test on dev first: Don't merge directly to master
2. Use descriptive commit messages: Makes it easier to track changes
3. Regular syncing: Keep dev branch up to date with master
4. Review deployments: Always check the deployed site after pushing
5. Environment parity: Keep dev and production configurations as similar as possible

Security Notes

• API tokens should be stored securely in GitLab CI/CD variables
• Never commit sensitive information to the repository
• Cloudflare automatically manages SSL certificates for preview URLs
• Preview deployments are publicly accessible by default
• Consider setting up branch protection rules in GitLab for master

Benefits of Cloudflare's Built-in Previews

1. Automatic: No manual configuration for new branches
2. Cost-effective: One project handles all environments
3. Clean URLs: Predictable URL pattern for all previews
4. Easy cleanup: Delete branch, preview deployment is removed
5. Fast: Cloudflare's global CDN for all deployments