Lessons Learned - Multi-Client Automation Pipeline

Executive Summary

Successfully built end-to-end automation for client onboarding, reducing setup time from 45 minutes to target of 3 minutes. Testing revealed 6 fixable issues that will improve reliability to near 100%.

What Worked Exceptionally Well

1. Cloudflare DNS Integration ⭐⭐⭐⭐⭐

Why it worked:

• Full API access with simple token auth
• Instant DNS record creation (no propagation delay for subdomains)
• Reliable API responses
• Clear error messages

Key Learning: Choose infrastructure with robust APIs from the start

Example:

# Creating DNS record takes ~500ms
curl -X POST "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/dns_records" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"type": "CNAME", "name": "client.dev", "content": "cname.vercel-dns.com"}'

# Resolution is instant
dig client.dev.freebeer.ai CNAME +short
# Returns: cname.vercel-dns.com. (immediately)

2. GitHub Template Repository Approach ⭐⭐⭐⭐⭐

Why it worked:

• Single source of truth for client projects
• Updates to template automatically benefit future clients
• GitHub's native template feature is simple and reliable
• gh repo create --template is fast and consistent

Key Learning: Platform-native features are more reliable than custom solutions

Example:

# One command creates perfect copy
gh repo create freebeerstudio/new-client \
  --template freebeerstudio/client-template \
  --public \
  --clone
# Takes ~3 seconds

3. Placeholder Variable System ⭐⭐⭐⭐

Why it worked:

• Simple pattern: {{VARIABLE_NAME}}
• Easy to spot in files
• sed replacement is fast and reliable
• No risk of partial replacements

Example:

# Template file
env:
  NEXT_PUBLIC_APP_NAME: "{{CLIENT_NAME}} - Dev"
  NEXT_PUBLIC_APP_URL: "https://{{CLIENT_SLUG}}.dev.freebeer.ai"

# After replacement
env:
  NEXT_PUBLIC_APP_NAME: "Acme Coffee - Dev"
  NEXT_PUBLIC_APP_URL: "https://acme-coffee.dev.freebeer.ai"

4. GitHub Actions for CI/CD ⭐⭐⭐⭐⭐

Why it worked:

• Zero configuration after secrets are set
• Automatic triggering on push
• Clear visibility of build/deploy status
• Free for public repositories
• Integrates perfectly with GitHub

Timeline:

Push to main → GitHub Actions → Build (24s) → Deploy (20s) → Live
Total time: ~70 seconds from code to production

5. Test-First Approach ⭐⭐⭐⭐

Why it worked:

• Used taptapteach.com to practice Cloudflare migration
• Found issues in safe environment
• Built confidence before production
• Validated every component independently

Timeline:

1. Test domain (taptapteach.com) - found no issues
2. Production domain (freebeer.ai) - executed flawlessly
3. Demo client (acme-coffee) - found 6 issues, all fixable

What Didn't Work (And How to Fix It)

Issue 1: Branch Naming Inconsistency

Problem:

• Template repository created with master branch
• Workflows configured for main branch
• Workflow didn't trigger on push

Root Cause: GitHub defaults changed, template not updated

Impact: Workflow required manual branch rename

Fix:

# In template repository
git branch -m master main
git push -u origin main
gh repo edit --default-branch=main

# Update .github/workflows/*.yml to reference 'main'

Issue 2: Missing package-lock.json

Problem:

• Template repository didn't include package-lock.json
• GitHub Actions cache setup failed
• First workflow run always failed

Root Cause: Template created from scratch, npm install never run

Fix:

# In template repository
npm install  # Generates package-lock.json
git add package-lock.json
git commit -m "Add package-lock.json for CI/CD caching"
git push

Issue 3: Background Process Timing

Problem:

• GitHub secret configuration ran in background
• Script continued before secrets were set
• Workflow failed with missing secrets

Fix:

# Bad (runs in background)
gh secret set KEY --body="value" &

# Good (waits for completion)
gh secret set KEY --body="value"

Issue 4: Git Remote URL Format

Problem:

• Repository cloned with HTTPS URL
• Push failed due to authentication
• Required credential input (not available in automation)

Fix:

# After clone, immediately change remote
git remote set-url origin git@github.com:freebeerstudio/$REPO_NAME.git

# Or configure gh CLI to use SSH
gh config set git_protocol ssh

Issue 5: Vercel Project ID Extraction

Problem:

• Tried to parse project ID from vercel inspect output
• Parsing failed due to format changes
• Script couldn't continue

Fix:

# Bad (parsing CLI output)
VERCEL_PROJECT_ID=$(npx vercel inspect | grep "Project ID:" | awk '{print $3}')

# Good (reading config file)
VERCEL_PROJECT_ID=$(cat .vercel/project.json | jq -r '.projectId')

Issue 6: Vercel Domain Authentication Scope

Problem:

• Token scoped to personal account
• Domain command tried to access organization
• Error: "Not authorized: Trying to access resource under scope 'freebeerstudio'"

Fix:

# Option 1: Re-authenticate with org scope
vercel login --scope freebeerstudio

# Option 2: Get new token with correct scope
# Via Vercel dashboard → Settings → Tokens

# Option 3: Handle error gracefully (domain still gets added)
npx vercel domains add $DOMAIN 2>&1 || true

Performance Metrics

Time Comparison

Scalability Impact

Cost Analysis

Development Investment

Break-even Point: 6 clients (6 × 42 min savings = 252 min = 4.2 hours)

ROI at 50 clients:

• Time saved: 35 hours
• Investment: 4.5 hours
• ROI: 678% (return 7.8x investment)

Key Takeaways

Recommendations

Immediate Actions (Before Next Client)

• Fix template repository: change default branch to main
• Run npm install to generate package-lock.json
• Update onboard-client.sh: configure gh to use SSH protocol
• Read Vercel project ID from config file instead of parsing CLI
• Remove background process markers from scripts
• Add error handling for each step
• Test improvements with second demo client

Short-term Improvements (Next Week)

• Add verification script for health checks
• Create rollback capability (remove-client.sh)
• Add pre-flight checks before starting automation
• Add comprehensive logging to all scripts

Long-term Improvements (Next Month)

• Add config file support (YAML/JSON) for bulk onboarding
• Create monitoring dashboard for all clients
• Build admin tools (list clients, status dashboard, bulk operations)