Free hosting deserves free tooling. Domain → GitHub Pages in 60 seconds.
gg-deploy is my latest: domain deployment automated, built in a weekend, open source, free forever. It's not going to save the world, but it might save you an hour of DNS configuration.
One command. One click. One prompt. Works via CLI, desktop app, web UI, or AI assistant (MCP).
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
GitHub Pages is free. Domain registration is cheap. But connecting them? That's still 15 minutes of DNS googling, A-record guessing, and "did I break my email forwarding again?" anxiety.
I wanted deployment to be as fast as the hosting is free (for public repos). So I built gg-deploy over a weekend; a CLI for power users, web UI for everyone else, MCP for AI agents, and desktop apps because why not.
AGPL-licensed because good tools should stay free.
Download from GitHub Releases:
.dmg (Apple Silicon or Intel).msi installer.AppImage or .debThe app isn't signed with an Apple certificate. On first launch:
Option 1: Right-click method
Option 2: Terminal (one command)
xattr -cr "/Applications/GG Deploy.app"
This is a one-time step—the app runs normally after.
Click More info → Run anyway on the SmartScreen prompt.
Make executable and run:
chmod +x GG.Deploy_*.AppImage
./GG.Deploy_*.AppImage
node --version| Provider | Ease of Setup | API Access | Notes |
|---|---|---|---|
| Cloudflare | Easy | Free for all | Recommended for new users |
| GoDaddy | Medium | Requires 10+ domains | Production key required |
| Namecheap | Medium | Requires IP whitelist | Must whitelist your IP |
Credentials are saved once to ~/.gg-deploy/config.json and work across all projects.
npx gg-deploy ui
The setup wizard walks you through:
Create ~/.gg-deploy/config.json with your preferred DNS provider:
Cloudflare (Recommended):
{
"dnsProvider": "cloudflare",
"cloudflare": {
"apiToken": "YOUR_CLOUDFLARE_TOKEN"
},
"github": {
"token": "ghp_YOUR_TOKEN"
}
}
GoDaddy:
{
"dnsProvider": "godaddy",
"godaddy": {
"apiKey": "YOUR_KEY",
"apiSecret": "YOUR_SECRET",
"environment": "production"
},
"github": {
"token": "ghp_YOUR_TOKEN"
}
}
Namecheap:
{
"dnsProvider": "namecheap",
"namecheap": {
"apiUser": "YOUR_USERNAME",
"apiKey": "YOUR_API_KEY",
"clientIP": "YOUR_IP_ADDRESS"
},
"github": {
"token": "ghp_YOUR_TOKEN"
}
}
Cloudflare API Token (Recommended):
GoDaddy API Key:
Namecheap API:
curl ifconfig.meGitHub Token:
ghp_)| Element | Description |
|---|---|
| Domain field | Your GoDaddy domain (e.g., example.com) |
| Repository field | GitHub repo as username/repo |
| Deploy button | Starts the deployment process |
| Status badges | Show GoDaddy/GitHub connection status |
| Settings gear | Opens credential management |
| Color | Meaning |
|---|---|
| Green (glowing) | Connected and verified |
| Yellow (pulsing) | Testing connection... |
| Red | Error (hover for details) |
| Gray | Not tested yet |
Hover over badges for detailed status. Click the refresh button to re-test connections.
| Command | Description | Safe | Git Required |
|---|---|---|---|
plan <domain> <repo> | Preview changes | Yes | No |
apply <domain> <repo> | Execute deployment | No | No |
status <domain> <repo> | Check health | Yes | No |
list | Show all tracked deployments | Yes | No |
push [domain] [message] | Upload local file changes | No | No |
forget <domain> | Remove from tracking | Yes | No |
ui | Launch web interface | Yes | No |
mcp-serve | Start MCP server | Yes | No |
update | Check for updates | Yes | No |
describe | Output AI-friendly tool schema | Yes | No |
Add --output json for machine-readable output.
The push command uploads your local files directly to GitHub via API—no git knowledge required:
# From your project directory (auto-detects deployment)
gg-deploy push "Updated homepage"
# Or specify the domain explicitly
gg-deploy push myblog.com "Fixed typo in about page"
How it works:
Respects .gitignore and .gg-ignore — node_modules, .env, and other patterns are automatically excluded.
After apply succeeds, gg-deploy remembers your deployment:
# List all tracked deployments
gg-deploy list
# Output:
# ╭─ Tracked Deployments ─────────────────────────────────────╮
# │ myblog.com → user/blog │
# │ └─ /Users/me/projects/myblog │
# │ Last activity: 2 hours ago │
# ╰───────────────────────────────────────────────────────────╯
To stop tracking (doesn't affect live site):
gg-deploy forget myblog.com
Note: forget only removes local tracking. Your DNS records and GitHub Pages remain active. See the output for cleanup instructions.
gg-deploy includes a full MCP (Model Context Protocol) server, enabling AI assistants to deploy and manage sites directly.
Compatible with:
Claude Desktop / Claude Code — Add to config:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"gg-deploy": {
"command": "npx",
"args": ["-y", "gg-deploy", "mcp-serve"]
}
}
}
Cursor / Windsurf — Add to MCP settings with the same configuration.
N8N — Use the MCP node with command: npx -y gg-deploy mcp-serve
| Tool | Description | Safe |
|---|---|---|
deploy_site_plan | Preview deployment changes | Yes |
deploy_site_apply | Execute DNS + GitHub Pages deployment | No |
deploy_site_status | Check deployment health | Yes |
list_deployments | List all tracked deployments | Yes |
push_changes | Upload local file changes | No |
Run gg-deploy describe to get a comprehensive JSON schema with:
| Problem | Solution |
|---|---|
node: command not found | Install Node.js from https://nodejs.org |
unsupported engine | Upgrade to Node.js 18+ |
EACCES permission denied | Don't use sudo. Fix npm permissions or use nvm |
| Problem | Solution |
|---|---|
401 Unauthorized | Wrong API key/secret. Regenerate at developer.godaddy.com |
403 Forbidden | API key is for OTE (test). Create a Production key |
404 Not Found | Domain not in your GoDaddy account |
422 Invalid | Domain locked or has pending transfers |
403 Access denied | Account needs 10+ domains for API. Use Cloudflare instead |
| Red status dot | Hover for error. Usually auth issue |
| Problem | Solution |
|---|---|
401 Unauthorized | Invalid API token. Regenerate at dash.cloudflare.com |
403 Forbidden | Token doesn't have Edit DNS permission. Create new token |
| Zone not found | Domain not in your Cloudflare account or wrong zone |
| Records not applying | Ensure proxied: false for GitHub Pages (handled automatically) |
| Problem | Solution |
|---|---|
1011150 IP not whitelisted | Add your IP at ap.www.namecheap.com/settings/tools/apiaccess |
500000 Rate limited | Wait a few minutes, API has rate limits |
| Authentication failed | Check apiUser and apiKey are correct |
| Domain not found | Domain must be active in your Namecheap account |
| Records overwritten | Namecheap API replaces ALL records. Backup is created automatically |
| Problem | Solution |
|---|---|
401 Bad credentials | Token expired or invalid. Generate new one |
403 Forbidden | Token missing repo scope. Regenerate with correct scope |
404 Not Found | Repo doesn't exist or token can't access it |
| Private repo fails | Need GitHub Pro for private repo Pages |
| Problem | Solution |
|---|---|
| Site not loading | Wait 10-60 min for DNS propagation |
| Wrong IP showing | Clear DNS cache: sudo dscacheutil -flushcache (Mac) |
| SSL not working | GitHub needs DNS to resolve first. Check Pages settings |
| Problem | Solution |
|---|---|
| "Not configured" | Check ~/.gg-deploy/config.json exists |
| Can't find config | It's in your home directory: ls -la ~/.gg-deploy/ |
| Permission denied | Run chmod 600 ~/.gg-deploy/config.json |
| Problem | Solution |
|---|---|
| Port 3847 in use | Kill existing: lsof -i :3847 then kill <PID> |
| Blank page | Clear browser cache or try incognito |
| Eye icon not working | Click reveals value if credentials are saved |
# 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
Total time: ~60 seconds. DNS propagation: 10-60 minutes.
~/.gg-deploy/config.json (permission 600)AGPL-3.0 — Free to use, modify, and distribute. Forks must remain open source.
Hola. I'm Abe Diaz. By day, I'm Sr. Manager of Disaster Relief at Amazon, leading a team that uses AI and logistics to deliver 26+ million relief items and response technology across 200+ disasters worldwide. On weekends, I build artisanal developer tools like this :-P
| Project | Description |
|---|---|
| gemini-deep-research | CLI for Gemini's Deep Research Agent |
| aipm-resume-analyzer | Resume analysis against AI PM frameworks |
| project-kickoff | Scaffold AI production-ready projects |
FAQs
Free hosting deserves free tooling. Domain → GitHub Pages in 60 seconds.
We found that gg-deploy demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.