GitHub Pages Custom Domain Management

Diagnose and manage the custom domain setup for arova-ai.com on GitHub Pages.

Architecture

arova-ai.com (apex)          → GitHub Pages A records (4 IPs)
www.arova-ai.com (www)       → CNAME to arova-ai.github.io
GitHub Pages custom domain   → arova-ai.com (apex is the primary)
SSL certificate              → Let's Encrypt, covers both apex + www

Key Facts

• Repo: arova-ai/arova-website
• Primary domain: arova-ai.com (apex)
• GitHub Pages IPs (for A records):
• 185.199.108.153
• 185.199.109.153
• 185.199.110.153
• 185.199.111.153
• CNAME file: public/CNAME contains arova-ai.com
• DNS provider: Gandi (use gandi-arova skill for API calls)
• SSL: Let's Encrypt via GitHub Pages, auto-renewed

Diagnostic Workflow

When something is wrong with the domain, run these checks in order:

1. DNS Resolution

# Check apex A records
dig arova-ai.com A +short
# Expected: 4 GitHub Pages IPs

# Check www CNAME
dig www.arova-ai.com CNAME +short
# Expected: arova-ai.github.io.

# Use external DNS to bypass cache
dig arova-ai.com A @8.8.8.8 +short
dig www.arova-ai.com CNAME @1.1.1.1 +short

2. HTTP/HTTPS Access

# Test apex
curl -sI -o /dev/null -w "HTTPS %{http_code}" https://arova-ai.com
# Expected: 200

# Test www (should redirect to apex)
curl -sI -o /dev/null -w "%{http_code} → %{redirect_url}" https://www.arova-ai.com
# Expected: 301 → https://arova-ai.com/

# Test HTTP redirect
curl -sI -o /dev/null -w "%{http_code} → %{redirect_url}" http://arova-ai.com
# Expected: 301 → https://arova-ai.com/

3. SSL Certificate

# Check what cert is being served
echo | openssl s_client -servername arova-ai.com -connect 185.199.108.153:443 2>/dev/null | grep "subject="
# Expected: CN=arova-ai.com (NOT *.github.io)

# Check www cert
echo | openssl s_client -servername www.arova-ai.com -connect 185.199.108.153:443 2>/dev/null | grep "subject="

4. GitHub Pages Config

gh api repos/arova-ai/arova-website/pages | jq '{cname, https_enforced, cert_state: .https_certificate.state, domains: .https_certificate.domains}'

Common Issues & Fixes

Issue: SSL certificate shows *.github.io instead of custom domain

Cause: GitHub Pages hasn't provisioned a Let's Encrypt cert yet. Fix: Wait 5-15 minutes. Check cert state via gh api. If stuck, toggle the custom domain:

gh api repos/arova-ai/arova-website/pages -X PUT -f cname=""
sleep 10
gh api repos/arova-ai/arova-website/pages -X PUT -f cname="arova-ai.com"

Issue: www.arova-ai.com HTTPS fails

Cause: www CNAME points to apex (arova-ai.com.) instead of arova-ai.github.io. Fix: Update www CNAME on Gandi (use gandi-arova skill):

# WRONG: www → arova-ai.com.  (SSL cert won't cover www)
# RIGHT: www → arova-ai.github.io.  (GitHub Pages serves + gets cert)

The www CNAME must point to arova-ai.github.io. so GitHub Pages can:

1. Serve the site from its servers
2. Include www in the SSL certificate
3. Return a 301 redirect to the apex domain

Issue: arova-ai.com redirects to www.arova-ai.com

Cause: GitHub Pages custom domain is set to www.arova-ai.com instead of arova-ai.com. Fix: The custom domain setting controls which is primary. Keep it as apex:

gh api repos/arova-ai/arova-website/pages -X PUT -f cname="arova-ai.com"

And ensure public/CNAME contains arova-ai.com.

Issue: HTTPS enforcement fails ("certificate not yet issued")

Cause: Let's Encrypt cert is still being provisioned. Fix: Wait and retry:

# Check cert state
gh api repos/arova-ai/arova-website/pages | jq '.https_certificate.state'
# "new" = provisioning, "approved" = ready, "dns_changed" = re-provisioning

# Once cert is ready:
gh api repos/arova-ai/arova-website/pages -X PUT -F https_enforced=true

Issue: Local DNS cache shows old records

Fix: Flush macOS DNS cache:

sudo dscacheutil -flushcache && sudo killall -HUP mDNSResponder

Correct DNS Setup (Reference)

Do NOT modify MX, SPF (TXT), or DKIM (gm1/gm2._domainkey CNAME) records — they are for email.

Pre-Change Checklist

Before making DNS changes:

1. Create a Gandi DNS snapshot (via gandi-arova skill)
2. List current records and confirm what exists
3. Make the change
4. Verify with dig using external DNS (@8.8.8.8)
5. Wait for propagation if needed