Runbook: Cloudflare Pages Git Provider Failover

Last Updated

2026-02-13

Owner

Evan Rosado

Frequency

As Needed (GitHub outage)

Purpose

Deploy documentation sites to Cloudflare Pages when the primary git provider (GitHub) is unavailable. This runbook documents the multi-provider redundancy strategy and failover procedures.

Architecture

Git Provider Redundancy

All domus-* repositories are mirrored to 3 providers:

Provider URL Pattern Location

GitHub (Primary)

github.com/EvanusModestus/*

Cloud

GitLab

gitlab.com/EvanusModestus/*

Cloud

Gitea

gitea-01.inside.domusdigitalis.dev/*

Self-hosted

Deployment Options

Method Trigger GitHub Required?

Cloudflare Pages Git Integration

Push to GitHub

Yes

Wrangler Direct Deploy

Manual CLI command

No

GitLab CI/CD + Wrangler

Push to GitLab

No

Prerequisites

  • wrangler CLI installed and authenticated

  • Access to at least one working git remote

  • Local clone of repository

  • Cloudflare API token with Pages:Edit permission

# Verify wrangler authentication
wrangler whoami

# Verify git remotes
git remote -v

Procedure

Option 1: Wrangler Direct Deploy (Fastest)

Use when GitHub is down and you need to deploy immediately.

Step 1: Pull Latest from Working Remote

# Try GitLab first
git pull gitlab main

# Or use self-hosted Gitea
git pull gitea main

Step 2: Build the Site

cd ~/atelier/_bibliotheca/domus-docs
make

Step 3: Deploy via Wrangler

wrangler pages deploy build/site --project-name=domus-docs

Expected output:

Uploading... (794/794)
Success! Uploaded 567 files (227 already uploaded)

Deploying...
Deployment complete! Take a peek over at https://a5568b3d.domus-docs.pages.dev

Step 4: Purge CDN Cache (Optional)

netapi cloudflare purge domusdigitalis.dev -y

Option 2: Switch Pages to GitLab

Use for longer GitHub outages when you want automatic deployments.

Step 1: Access Cloudflare Dashboard

Navigate to: Cloudflare Dashboard → Pages → domus-docs → Settings → Builds & deployments

Step 2: Disconnect GitHub

Click "Disconnect" under Git repository.

Step 3: Connect GitLab

  1. Click "Connect to Git"

  2. Select GitLab

  3. Authorize Cloudflare

  4. Select EvanusModestus/domus-docs

  5. Configure build settings:

    • Build command: npx antora antora-playbook.yml

    • Build output directory: build/site

    • Root directory: /

Step 4: Trigger Initial Deploy

Push any commit to GitLab to trigger deployment:

git push gitlab main

Option 3: Deploy All domus-* Sites

When multiple sites need updating during GitHub outage:

#!/bin/bash
# deploy-all-domus.sh

sites=(
    "domus-docs:build/site"
    "domus-captures:build/site"
)

for site_config in "${sites[@]}"; do
    IFS=':' read -r project output_dir <<< "$site_config"
    repo_path="$HOME/atelier/_bibliotheca/$project"

    if [[ -d "$repo_path" ]]; then
        echo "=== Deploying $project ==="
        cd "$repo_path"
        git pull gitlab main 2>/dev/null || git pull gitea main
        make
        wrangler pages deploy "$output_dir" --project-name="$project"
    fi
done

Verification

Check Deployment Status

# Via netapi
netapi cloudflare pages deployments domus-docs -n 1

# Via wrangler
wrangler pages deployment list --project-name=domus-docs | head -5

Verify Site is Live

# Check HTTP status
curl -sI https://docs.domusdigitalis.dev | head -1

# Check content updated (look for recent changes)
curl -s https://docs.domusdigitalis.dev | grep -o '<meta name="generator".*>'

Troubleshooting

Issue: Wrangler Authentication Failed

Symptom: Error: Authentication required

Cause: Wrangler token expired or not set

Resolution:

# Re-authenticate
wrangler login

# Or set token directly
export CLOUDFLARE_API_TOKEN="your-token"

Issue: Build Fails Locally

Symptom: Antora build errors

Cause: Missing dependencies or Kroki server not running

Resolution:

# Start Kroki
make kroki

# Reinstall dependencies
npm install

# Retry build
make

Issue: Cannot Pull from Any Remote

Symptom: All git pull commands fail

Cause: Network issues or all providers down (unlikely)

Resolution:

Deploy from existing local build (if recent):

# Check when build was last updated
ls -la build/site/index.html

# Deploy existing build
wrangler pages deploy build/site --project-name=domus-docs

Rollback

If a bad deployment was pushed:

# List recent deployments
wrangler pages deployment list --project-name=domus-docs

# Rollback to previous deployment (via dashboard)
# Cloudflare Dashboard → Pages → domus-docs → Deployments → [select previous] → "Rollback to this deployment"

Automation: domus-push-all Function

The domus-push zsh function pushes to all remotes for all domus-* repos:

# Push single repo to all remotes
gpall

# Push all domus-* repos to primary remote
domus-push

Location: ~/.zshrc

Industry Practice

This multi-provider strategy is standard practice:

Organization Strategy

GitLab.com

Mirrors to GitHub + self-hosted backup

Kubernetes SIGs

GitHub primary + GitLab mirrors

Netflix

Multi-region + multi-provider redundancy

Cloudflare

Recommends wrangler CLI as GitHub-down fallback

Related Documentation