gg-deploy

Free hosting deserves free tooling. Domain → GitHub Pages in 60 seconds.

Configure and connect any domain to free hosting via GitHub Pages—DNS, SSL, CNAME—automated. One command. One click. One prompt. Works via CLI, desktop app, web UI, or AI assistant (MCP).

Quick Start

npx gg-deploy ui
# Opens http://localhost:3847

Or via CLI:

npx gg-deploy plan example.com user/repo    # Preview (safe)
npx gg-deploy apply example.com user/repo   # Deploy
npx gg-deploy status example.com user/repo  # Health check

Requirements

• Node.js 18+ — Check with node --version
• GoDaddy account with 10+ domains (API access requirement)
• GitHub account with a Personal Access Token
• Domain on GoDaddy you want to point to GitHub Pages
• GitHub repo with your site content (index.html or built site)

Setup

Credentials are saved once to ~/.gg-deploy/config.json and work across all projects.

Option 1: Web UI (Recommended)

npx gg-deploy ui

The setup wizard walks you through:

1. Creating a GoDaddy API key
2. Creating a GitHub token
3. Testing and saving credentials

Option 2: Manual Config

Create ~/.gg-deploy/config.json:

{
  "godaddy": {
    "apiKey": "YOUR_KEY",
    "apiSecret": "YOUR_SECRET",
    "environment": "production"
  },
  "github": {
    "token": "ghp_YOUR_TOKEN"
  }
}

Getting Credentials

GoDaddy API Key:

1. Go to https://developer.godaddy.com/keys
2. Click "Create New API Key"
3. Select Production (not OTE/Test)
4. Copy Key and Secret immediately (secret shown only once)

GitHub Token:

1. Go to https://github.com/settings/tokens/new?description=gg-deploy&scopes=repo
2. Click "Generate token"
3. Copy the token (starts with ghp_)

Web Interface

Main Screen

Status Indicators

Hover over badges for detailed status. Click the refresh button to re-test connections.

Settings Screen

• API Key / Secret / Token fields — Pre-filled with saved values (masked)
• Eye icon — Click to reveal value for copying
• Status indicators — Show live verification status
• Test button — Re-verify API connections
• Update Settings — Save changes

Deployment Flow

1. Enter domain and repo
2. Click Deploy
3. Watch real-time progress:
   • Verify domain ownership
   • Check repository access
   • Configure DNS records
   • Add CNAME file
   • Enable GitHub Pages
   • Provision SSL certificate
4. Get your live URL

CLI Commands

Add --output json for machine-readable output.

Claude Code / MCP

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "gg-deploy": {
      "command": "npx",
      "args": ["-y", "gg-deploy", "mcp-serve"]
    }
  }
}

Then tell Claude: "Deploy example.com using user/repo"

Troubleshooting

Node.js Issues

GoDaddy API Issues

GitHub API Issues

DNS Issues

Config Issues

UI Issues

Common Fixes

# Check if config exists
cat ~/.gg-deploy/config.json

# Verify Node version
node --version  # Should be 18+

# Test GoDaddy API manually
curl -H "Authorization: sso-key YOUR_KEY:YOUR_SECRET" \
  https://api.godaddy.com/v1/domains

# Test GitHub API manually
curl -H "Authorization: Bearer ghp_YOUR_TOKEN" \
  https://api.github.com/user

How It Works

1. DNS — Sets A records to GitHub IPs (185.199.108-111.153) + www CNAME
2. CNAME — Creates CNAME file in repo with your domain
3. Pages — Enables GitHub Pages on main branch
4. SSL — GitHub auto-provisions Let's Encrypt certificate

Total time: ~60 seconds. DNS propagation: 10-60 minutes.

Security

• Credentials stored in ~/.gg-deploy/config.json (permission 600)
• Never committed to git
• Eye icon reveals values only locally
• API calls made directly to GoDaddy/GitHub (no proxy)

Limitations

• GoDaddy only (10+ domains required for API; Cloudflare/Namecheap coming)
• Public repos or GitHub Pro required for Pages
• Only www subdomain supported
• One domain per deployment

License

AGPL-3.0 — Free to use, modify, and distribute. Forks must remain open source.

Built by Abe Diaz | GitHub