blackroad-domains/GITHUB_CLOUDFLARE_AUTOMATION.md

GitHub to Cloudflare Seamless Deployment Guide

Owner: Alexa Louise Amundson Last Updated: 2025-12-22 Purpose: Automate all GitHub repos to deploy to Cloudflare Pages on push

---

🎯 Overview

This guide sets up automatic deployment from GitHub to Cloudflare Pages:

• Push to GitHub → Auto-deploy to Cloudflare Pages
• Pull Requests → Deploy to preview
• Merge to main → Deploy to production

No manual commands needed. Git push does everything.

---

🚀 Two Methods for Seamless Deployment

Method 1: Cloudflare Pages Git Integration (Recommended)

Easiest setup. No code required.

Method 2: GitHub Actions with Wrangler

More control. Customizable workflows.

---

📋 Method 1: Cloudflare Pages Git Integration

Setup Process

Step 1: Connect Repository to Cloudflare Pages

Via Cloudflare Dashboard:

1. Login to Cloudflare Dashboard

   • Go to https://dash.cloudflare.com
   • Select your account

2. Navigate to Pages

   • Click Workers & Pages in sidebar
   • Click Create application
   • Select Pages tab
   • Click Connect to Git

3. Authorize GitHub

   • Click Connect GitHub
   • Authorize Cloudflare Pages app
   • Select organization: blackboxprogramming or BlackRoad-OS

4. Select Repository

   • Choose repository (e.g., lucidia-metaverse)
   • Click Begin setup

5. Configure Build Settings

   For Next.js/React/Vite projects:

   Production branch: main
   Build command: npm run build
   Build output directory: dist (or build, or out)
   Root directory: / (or specific path)
   

   For static sites:

   Production branch: main
   Build command: (leave empty)
   Build output directory: / (or public)
   

6. Environment Variables (if needed)

   • Click Add variable
   • Add: NODE_VERSION = 18
   • Add any API keys or secrets

7. Save and Deploy

   • Click Save and Deploy
   • First deployment starts automatically

Step 2: Automatic Deployments

After setup, deployments happen automatically:

# Developer workflow
git add .
git commit -m "Update feature"
git push origin main

# Cloudflare automatically:
# 1. Detects push
# 2. Runs build
# 3. Deploys to production
# 4. Updates https://project-name.pages.dev

Step 3: Preview Deployments

Pull requests get preview URLs:

# Create feature branch
git checkout -b feature/new-ui
# Make changes
git add .
git commit -m "Add new UI"
git push origin feature/new-ui

# Create PR on GitHub
# Cloudflare automatically creates preview:
# https://abc123.project-name.pages.dev

Connected Repositories Configuration

All 58 Projects - Configuration Table

Repository	Pages Project	Build Command	Output Dir	Status
lucidia-metaverse	lucidia-earth	npm run build	dist	🔗 To Connect
blackroad-io	blackroad-io	npm run build	dist	🔗 To Connect
blackroad-os-web	blackroad-os-web	npm run build	dist	✅ Connected
roadworld	roadworld	npm run build	dist	🔗 To Connect
blackroad-hello	blackroad-hello	npm run build	dist	🔗 To Connect
...	...	...	...	...

To connect each repository:

1. Go to Pages → project → Settings → Builds & deployments
2. Click Connect to Git (if not connected)
3. Select repository
4. Configure build settings
5. Save

---

🔧 Method 2: GitHub Actions with Wrangler

Universal GitHub Actions Workflow

Create .github/workflows/deploy.yml in each repository:

name: Deploy to Cloudflare Pages

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      deployments: write

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Build project
        run: npm run build

      - name: Deploy to Cloudflare Pages
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          command: pages deploy dist --project-name=${{ secrets.PAGES_PROJECT_NAME }}

Setup GitHub Secrets

For each repository:

1. Go to Repository Settings

   • Navigate to repository on GitHub
   • Click Settings tab
   • Click Secrets and variables → Actions

2. Add Secrets

   • Click New repository secret

   Add three secrets:

   CLOUDFLARE_API_TOKEN

   Value: yP5h0HvsXX0BpHLs01tLmgtTbQurIKPL4YnQfIwy
   

   CLOUDFLARE_ACCOUNT_ID

   Value: 463024cf9efed5e7b40c5fbe7938e256
   

   PAGES_PROJECT_NAME

   Value: lucidia-earth (or project-specific name)
   

Automated Script to Add Workflows to All Repos

#!/usr/bin/env bash
# add-github-actions-to-all-repos.sh

REPOS=(
  "lucidia-metaverse:lucidia-earth"
  "blackroad-io:blackroad-io"
  "blackroad-os-web:blackroad-os-web"
  "roadworld:roadworld"
  "blackroad-hello:blackroad-hello"
  # Add all 58 repositories here
)

for repo_config in "${REPOS[@]}"; do
  IFS=':' read -r repo_name project_name <<< "$repo_config"

  echo "Setting up $repo_name → $project_name"

  # Clone or update repo
  if [ -d "$repo_name" ]; then
    cd "$repo_name"
    git pull origin main
  else
    gh repo clone "BlackRoad-OS/$repo_name"
    cd "$repo_name"
  fi

  # Create GitHub Actions workflow
  mkdir -p .github/workflows

  cat > .github/workflows/deploy.yml << EOF
name: Deploy to Cloudflare Pages

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      deployments: write

    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Build
        run: npm run build

      - name: Deploy to Cloudflare Pages
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: \${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: \${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          command: pages deploy dist --project-name=$project_name
EOF

  # Commit and push
  git add .github/workflows/deploy.yml
  git commit -m "Add automated Cloudflare Pages deployment"
  git push origin main

  # Set GitHub secrets
  gh secret set CLOUDFLARE_API_TOKEN --body "yP5h0HvsXX0BpHLs01tLmgtTbQurIKPL4YnQfIwy"
  gh secret set CLOUDFLARE_ACCOUNT_ID --body "463024cf9efed5e7b40c5fbe7938e256"
  gh secret set PAGES_PROJECT_NAME --body "$project_name"

  cd ..
  echo "✅ Completed $repo_name"
done

echo "🎉 All repositories configured for automatic deployment!"

Make it executable:

chmod +x add-github-actions-to-all-repos.sh

---

🌐 Organization-Wide GitHub Secrets (Recommended)

Instead of setting secrets per-repo, set them organization-wide.

Setup Organization Secrets

1. Go to Organization Settings

   • Navigate to https://github.com/organizations/BlackRoad-OS/settings/secrets/actions
   • Or: GitHub → Your organizations → BlackRoad-OS → Settings → Secrets and variables → Actions

2. Add Organization Secrets

   • Click New organization secret

   CLOUDFLARE_API_TOKEN

   Value: yP5h0HvsXX0BpHLs01tLmgtTbQurIKPL4YnQfIwy
   Repository access: All repositories
   

   CLOUDFLARE_ACCOUNT_ID

   Value: 463024cf9efed5e7b40c5fbe7938e256
   Repository access: All repositories
   

3. Set Project-Specific Secret Per Repo

   • Only PAGES_PROJECT_NAME needs to be set per repository

Benefits:

• Set secrets once for entire organization
• Automatic access for all repos
• Easy secret rotation

---

📦 Complete Repository Configuration Matrix

All 58 Cloudflare Pages Projects

#	Repository	Pages Project	Auto-Deploy	Build Cmd	Output
1	lucidia-metaverse	lucidia-earth	🔗 Setup	npm run build	dist
2	blackroad-io	blackroad-io	🔗 Setup	npm run build	dist
3	blackroad-os-web	blackroad-os-web	✅ Active	npm run build	dist
4	blackroad-os-prism	blackroad-os-prism	🔗 Setup	npm run build	dist
5	blackroad-os-demo	blackroad-os-demo	🔗 Setup	npm run build	dist
6	blackroad-os-home	blackroad-os-home	🔗 Setup	npm run build	dist
7	blackroad-os-brand	blackroad-os-brand	🔗 Setup	npm run build	dist
8	earth-blackroad-io	earth-blackroad-io	🔗 Setup	npm run build	dist
9	roadworld	roadworld	🔗 Setup	npm run build	dist
10	blackroad-hello	blackroad-hello	🔗 Setup	npm run build	dist
...	...	...	...	...	...
58	(all projects)	(all projects)	🔗 Setup	varies	varies

Legend:

• ✅ Active - Already connected and deploying
• 🔗 Setup - Needs configuration
• ⚠️ Review - Needs build config check

---

🔄 Deployment Workflow Comparison

Before (Manual):

# Developer has to:
cd ~/lucidia-metaverse
git pull origin main
npm install
npm run build
wrangler pages deploy dist --project-name=lucidia-earth

After (Automatic):

# Developer only does:
git push origin main

# Everything else happens automatically on Cloudflare/GitHub

Time saved: ~5 minutes per deployment × multiple deployments daily = Hours saved weekly

---

🎨 Enhanced Workflows

Multi-Environment Deployment

name: Deploy to Cloudflare Pages

on:
  push:
    branches: [main, staging, develop]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '18'
      - run: npm ci
      - run: npm run build

      - name: Deploy to Production
        if: github.ref == 'refs/heads/main'
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          command: pages deploy dist --project-name=lucidia-earth --branch=production

      - name: Deploy to Staging
        if: github.ref == 'refs/heads/staging'
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          command: pages deploy dist --project-name=lucidia-earth --branch=staging

      - name: Deploy to Development
        if: github.ref == 'refs/heads/develop'
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          command: pages deploy dist --project-name=lucidia-earth --branch=develop

With Testing and Linting

name: Test, Build, and Deploy

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '18'
      - run: npm ci
      - run: npm run lint
      - run: npm test

  deploy:
    needs: test
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '18'
      - run: npm ci
      - run: npm run build
      - uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          command: pages deploy dist --project-name=lucidia-earth

---

🚀 Quick Start Guide

For a Single Repository

Method 1: Cloudflare Dashboard (5 minutes)

1. Login to Cloudflare → Pages → Create application → Connect to Git
2. Select repository
3. Configure build: npm run build, output: dist
4. Save and Deploy
5. Done! Future pushes auto-deploy

Method 2: GitHub Actions (10 minutes)

1. Create .github/workflows/deploy.yml in your repo
2. Copy the workflow template above
3. Set GitHub secrets (CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID, PAGES_PROJECT_NAME)
4. Push to GitHub
5. Done! Future pushes auto-deploy

For All 58 Repositories

Option A: Cloudflare Dashboard (Manual but simple)

• Go through each repository in Cloudflare Pages
• Click "Connect to Git"
• Select repository
• Configure and save
• Repeat 58 times (~2 hours total)

Option B: Automated Script (Faster)

# Run the automation script
./add-github-actions-to-all-repos.sh

# Sits back and watches automation magic
# Completes in ~20 minutes

---

📊 Monitoring Deployments

Via Cloudflare Dashboard

1. Go to Workers & Pages
2. Click on project name
3. View Deployments tab
4. See:
   • Build logs
   • Deployment status
   • Preview URLs
   • Production URL

Via GitHub Actions

1. Go to repository on GitHub
2. Click Actions tab
3. See workflow runs
4. Click run to see logs

Via Wrangler CLI

# List recent deployments
wrangler pages deployment list --project-name=lucidia-earth

# Tail deployment logs
wrangler pages deployment tail

# View specific deployment
wrangler pages deployment view <deployment-id> --project-name=lucidia-earth

---

🔐 Security Best Practices

API Token Management

Create a scoped API token:

1. Go to Cloudflare Dashboard → Profile → API Tokens
2. Click Create Token
3. Use template: Edit Cloudflare Workers
4. Permissions:
   • Account → Cloudflare Pages → Edit
   • Zone → Zone → Read (if using custom domains)
5. Set token expiration (optional but recommended)
6. Create token and save it securely

Store in GitHub:

• Organization secrets (recommended for all repos)
• Repository secrets (for specific repos)
• Never commit tokens to code

Secret Rotation

Quarterly rotation recommended:

# Update organization secret
gh secret set CLOUDFLARE_API_TOKEN --org BlackRoad-OS --body "new-token-here"

# Or update per repository
gh secret set CLOUDFLARE_API_TOKEN --repo BlackRoad-OS/lucidia-metaverse --body "new-token-here"

---

🎯 Deployment Checklist

Initial Setup (One-time)

• Choose deployment method (Cloudflare Git Integration or GitHub Actions)
• Set up organization-wide GitHub secrets
• Configure first repository as template
• Test deployment workflow
• Document repository-specific requirements

Per Repository

• Create or update .github/workflows/deploy.yml
• Set repository secret PAGES_PROJECT_NAME
• Configure build settings
• Test with a commit
• Verify deployment at https://project-name.pages.dev
• Add custom domain (if needed)

Ongoing Maintenance

• Monitor deployment success rates
• Review failed deployments
• Update Node.js version as needed
• Rotate API tokens quarterly
• Update workflow templates

---

🌐 Custom Domain Configuration

After automatic deployment is working, add custom domains:

# Via Cloudflare Dashboard
# Pages → Project → Custom domains → Add domain

# Supported domain mappings:
lucidia-earth.pages.dev → lucidia.earth
blackroad-io.pages.dev → blackroad.io
blackroad-os-web.pages.dev → blackroadqi.com, blackroadquantum.*

DNS automatically configured by Cloudflare when you add custom domain.

---

📈 Benefits Summary

Automatic Deployment Benefits

✅ Developer Experience

• No manual deployment commands
• git push does everything
• Faster iteration cycles

✅ Reliability

• Consistent builds
• No human error
• Automated testing (if configured)

✅ Productivity

• ~5 min saved per deployment
• Multiple deployments per day
• Hours saved weekly across team

✅ Collaboration

• Preview URLs for PRs
• Easy code review
• Stakeholder previews

✅ Rollback

• One-click rollback in Cloudflare
• Git revert for code rollback
• Deployment history preserved

---

🔧 Troubleshooting

Common Issues

Build fails:

Check:
- Build command is correct
- Output directory exists
- All dependencies in package.json
- Environment variables set

Deployment succeeds but site broken:

Check:
- Output directory setting
- Base path in build config
- Environment variables
- CORS settings

GitHub Actions not triggering:

Check:
- Workflow file in .github/workflows/
- File has .yml or .yaml extension
- Secrets are set correctly
- Branch name matches workflow trigger

Debug Commands

# Test build locally
npm run build

# Check output directory
ls -la dist/

# Test with wrangler locally
wrangler pages dev dist

# View deployment logs
wrangler pages deployment tail --project-name=lucidia-earth

---

📚 Additional Resources

Documentation

• Cloudflare Pages Docs: https://developers.cloudflare.com/pages/
• GitHub Actions Docs: https://docs.github.com/en/actions
• Wrangler Docs: https://developers.cloudflare.com/workers/wrangler/

Support

• Cloudflare Community: https://community.cloudflare.com/
• GitHub Support: https://support.github.com/

---

🎉 Next Steps

1. Choose deployment method (Cloudflare Git or GitHub Actions)
2. Set up first repository as proof of concept
3. Test workflow with a commit
4. Roll out to all repositories using automation script
5. Monitor and optimize deployment times

---

Once configured, you'll never manually deploy again. Every git push becomes a production deployment. 🚀

---

"Push once, deploy everywhere." 🛣️

Generated by: Claude Code (Cece) Last Updated: 2025-12-22