blackroad-domains/CLOUDFLARE_GIT_INTEGRATION_GUIDE.md

Cloudflare Git Integration - Complete Setup Guide

Owner: Alexa Louise Amundson Last Updated: 2025-12-22 Status: ✅ RECOMMENDED METHOD

---

Why Use Cloudflare Git Integration?

After testing both GitHub Actions and Cloudflare Git Integration, Git Integration is the recommended approach because:

✅ No API tokens to manage - No secrets, no expiration issues ✅ Native Cloudflare integration - Built into the dashboard ✅ Automatic deployments - Push to GitHub = instant deployment ✅ Preview deployments - Every PR gets a preview URL ✅ Zero configuration - Just connect and go ✅ No workflow files needed - Cloudflare handles CI/CD

Tested Results

✅ Working Example: lucidia-metaverse

• GitHub Repo: BlackRoad-OS/lucidia-metaverse
• Pages Project: lucidia-earth
• Live URL: https://lucidia-earth.pages.dev
• Status: Deployed successfully via manual deployment
• Next Step: Connect to Git Integration

❌ GitHub Actions Issues Found

• API token authentication errors (code: 10000)
• Requires security policy compliance (SHA pinning)
• Needs manual secret management across 58 repositories
• More complex troubleshooting

---

Setup Process (5 Minutes Per Repo)

Step 1: Connect Repository to Cloudflare

1. Visit Cloudflare Pages Dashboard

   https://dash.cloudflare.com/848cf0b18d51e0170e0d1537aec3505a/pages
   

2. Select Your Project

   • Click on the Pages project (e.g., lucidia-earth)
   • Go to Settings → Builds & deployments

3. Connect to Git

   • Click Connect to Git
   • Choose GitHub as the provider
   • Authorize Cloudflare (one-time OAuth)
   • Select the organization: BlackRoad-OS
   • Select the repository (e.g., lucidia-metaverse)

4. Configure Build Settings

   • Production branch: main or master
   • Build command: npm run build
   • Build output directory: dist
   • Node version: 18

5. Save and Deploy

   • Click Save
   • Cloudflare will trigger the first build automatically

Step 2: Verify Automatic Deployment

1. Make a test commit to the repository

   cd ~/lucidia-metaverse
   echo "# Test auto-deploy" >> README.md
   git add README.md
   git commit -m "Test Cloudflare Git Integration"
   git push origin master
   

2. Watch the build in Cloudflare Dashboard

   • Builds appear in real-time
   • Usually complete in 1-2 minutes
   • Preview URL for each commit

3. Check deployment status

   wrangler pages deployment list --project-name=lucidia-earth
   

---

Repository to Project Mappings

All 58 repositories with their Pages projects:

Lucidia Ecosystem

GitHub Repo	Pages Project	Build Output	Custom Domain
lucidia-metaverse	lucidia-earth	dist	lucidia.earth
lucidia-platform	lucidia-platform	dist	-
lucidia-core	lucidia-core	dist	-
lucidia-math	lucidia-math	dist	-

BlackRoad Core

GitHub Repo	Pages Project	Build Output	Custom Domain
blackroad-io	blackroad-io	dist	blackroad.io
blackroad-os-web	blackroad-os-web	dist	Multiple domains
blackroad-os-prism	blackroad-os-prism	dist	-
blackroad-os-demo	blackroad-os-demo	dist	demo.blackroad.io
blackroad-os-home	blackroad-os-home	dist	-
blackroad-os-brand	blackroad-os-brand	dist	-
blackroad-os-docs	blackroad-os-docs	dist	-
earth-blackroad-io	earth-blackroad-io	dist	earth.blackroad.io

BlackRoad Services (26 repos)

GitHub Repo	Pages Project	Build Output
blackroad-hello	blackroad-hello	dist
blackroad-metaverse	blackroad-metaverse	dist
blackroad-console	blackroad-console	dist
blackroad-prism-console	blackroad-prism-console	dist
blackroad-admin	blackroad-admin	dist
blackroad-dashboard	blackroad-dashboard	dist
blackroad-chat	blackroad-chat	dist
blackroad-agents	blackroad-agents	dist
blackroad-agents-spawner	blackroad-agents-spawner	dist
blackroad-tools	blackroad-tools	dist
blackroad-analytics	blackroad-analytics	dist
blackroad-api	blackroad-api	dist
blackroad-api-explorer	blackroad-api-explorer	dist
blackroad-builder	blackroad-builder	dist
blackroad-workflows	blackroad-workflows	dist
blackroad-store	blackroad-store	dist
blackroad-payment-page	blackroad-payment-page	dist
blackroad-buy-now	blackroad-buy-now	dist
blackroad-company	blackroad-company	dist
blackroad-docs-hub	blackroad-docs-hub	dist

BlackRoad Infrastructure (16 repos)

GitHub Repo	Pages Project	Build Output
blackroad-portals	blackroad-portals	dist
blackroad-portals-unified	blackroad-portals-unified	dist
blackroad-unified	blackroad-unified	dist
blackroad-gateway-web	blackroad-gateway-web	dist
blackroad-assets	blackroad-assets	dist
blackroad-status	blackroad-status	dist
blackroad-status-new	blackroad-status-new	dist
blackroad-pitstop	blackroad-pitstop	dist
blackroad-systems	blackroad-systems	dist
blackroad-me	blackroad-me	dist

Road Ecosystem (7 repos)

GitHub Repo	Pages Project	Build Output
roadworld	roadworld	dist
roadwork	roadwork	dist
roadwork-production	roadwork-production	dist
roadchain-io	roadchain-io	dist
roadchain-production	roadchain-production	dist
roadcoin-io	roadcoin-io	dist
roadcoin-production	roadcoin-production	dist

Other (4 repos)

GitHub Repo	Pages Project	Build Output
operations-portal	operations-portal	dist
remotejobs-platform	remotejobs-platform	dist
applier-blackroad	applier-blackroad	dist
blackroad-hello-test	blackroad-hello-test	dist

---

Bulk Setup Script

For setting up all repositories at once:

#!/usr/bin/env bash
# cloudflare-git-integration-bulk.sh
# Connects all BlackRoad GitHub repos to Cloudflare Pages via Git Integration

# Note: This requires manual OAuth approval in the browser for each repo
# The Cloudflare UI doesn't have a bulk API, so we use the dashboard

echo "🚀 Cloudflare Git Integration Bulk Setup"
echo "=========================================="
echo ""
echo "Visit: https://dash.cloudflare.com/848cf0b18d51e0170e0d1537aec3505a/pages"
echo ""
echo "For each project:"
echo "  1. Click on project name"
echo "  2. Settings → Builds & deployments"
echo "  3. Connect to Git → Select GitHub repo"
echo "  4. Configure: npm run build → dist"
echo "  5. Save"
echo ""
echo "Total projects to connect: 58"
echo ""
read -p "Press Enter to open Cloudflare dashboard..."
open "https://dash.cloudflare.com/848cf0b18d51e0170e0d1537aec3505a/pages"

---

Troubleshooting

Issue: Build fails with "Command not found"

Solution: Check build command is npm run build not npm build

Issue: Wrong output directory

Solution: Verify output is dist (most Vite projects use this)

Issue: Node version mismatch

Solution: Set Node version to 18 in build settings

Issue: Repository not showing up

Solution: Make sure GitHub App has access to BlackRoad-OS organization

---

Comparison: Git Integration vs GitHub Actions

Feature	Git Integration	GitHub Actions
Setup Time	5 min/repo	10 min/repo
API Tokens	None ✅	Required ❌
Secrets Management	None ✅	Manual ❌
Security Compliance	Automatic ✅	SHA pinning required ❌
Preview Deploys	Built-in ✅	Manual config ❌
Troubleshooting	Simple ✅	Complex ❌
Recommendation	USE THIS ✅	Avoid unless needed

---

Next Steps

1. ✅ lucidia-metaverse → lucidia-earth (Tested, ready to connect)
2. Connect remaining 57 repositories using the same process
3. Remove GitHub Actions workflow files (they're not needed)
4. Update documentation to reflect Git Integration as standard

---

"Push to GitHub. Deploy to the world. That simple." 🚀