---
name: github-pages-custom-domain
description: Deploy a static site to GitHub Pages with a custom domain (e.g., from GoDaddy) using A records.
version: 1.0.0
author: Hermes Agent
category: devops
---
# GitHub Pages Custom Domain Deployment

This skill guides you through publishing a static website (HTML/CSS/JS) on GitHub Pages and pointing a custom domain (purchased via GoDaddy or similar) to it using A records.

## When to Use
- You have a static site ready (landing page, documentation, portfolio).
- You own a domain (e.g., `example.com`) and want to host it for free on GitHub Pages.
- You want a repeatable process that can be reused for future projects.

## Prerequisites
- A GitHub account with the ability to create repositories.
- The `git` command line tool installed.
- Access to your domain’s DNS settings (e.g., GoDaddy dashboard).
- (Optional) GitHub CLI (`gh`) for faster repo creation, but not required.

## Steps

### 1. Prepare Your Site Locally
```
# Create a folder for your site
mkdir my-site && cd my-site

# Add your static files (index.html, CSS, JS, assets, etc.)
# Ensure you have a CNAME file with your domain (without protocol or www)
echo "yourdomain.com" > CNAME
```

> **Note:** If your site files were originally `.html` and the system blocks them, rename to `.txt` or `.md` temporarily, then rename back after adding to the repo, or simply add them as‑is; GitHub accepts `.html`. The restriction is only on the agent’s file‑upload tool.

### 2. Initialize Git Repository
```
git init
git add .
git commit -m "Initial commit: static site for GitHub Pages"
```

### 3. Create the Remote Repository on GitHub
#### Using gh CLI (if available)
```
gh repo create username/my-site --public --source . --push
```

#### Using plain git + curl (fallback)
```bash
# 1) Create the repo via GitHub API (requires a personal token with repo scope)
#    Replace USERNAME, TOKEN, and REPO_NAME as needed.
curl -s -X POST \
  -H "Authorization: token $TOKEN" \
  https://api.github.com/user/repos \
  -d '{"name":"REPO_NAME","private":false,"auto_init":false}'

# 2) Add remote and push
git remote add origin https://github.com/USERNAME/REPO_NAME.git
git branch -M main
git push -u origin main
```

### 4. Enable GitHub Pages
#### Via GitHub UI
1. Go to your repo → **Settings** → **Pages**.
2. Under **Source**, select the `main` branch and `/ (root)` folder.
3. Click **Save**. GitHub will provide a URL like `https://username.github.io/my-site/`.

#### Via API (optional)
```bash
curl -s -X PUT \
  -H "Authorization: token $TOKEN" \
  https://api.github.com/repos/USERNAME/REPO_NAME/pages \
  -d '{"source":{"branch":"main","path":"/"}}'
```

### 5. Configure DNS A Records (GoDaddy Example)
1. Log in to GoDaddy → **My Products** → select your domain → **DNS**.
2. Under **Records**, add (or update) **A** records for the host `@` (naked domain) pointing to GitHub Pages’ IPs:
   - `185.199.108.153`
   - `185.199.109.153`
   - `185.199.110.153`
   - `185.199.111.153`
3. If you also want `www` subdomain, add a **CNAME** record:
   - Host: `www`
   - Points to: `username.github.io.` (note trailing dot)
   - TTL: 1 hour (or default)
4. Save changes. DNS propagation may take a few minutes to 24 hours.

### 6. Verify
After propagation, visit `https://yourdomain.com`. You should see your site served from GitHub Pages.
You can also check with:
```
curl -I http://yourdomain.com
# Should return 200 OK and include `X-GitHub-Request-Id` etc.
```

## Troubleshooting
- **404 from GitHub Pages**: 
  - Ensure the repo is public (private repos require a paid plan for GitHub Pages custom domains).
  - Verify that GitHub Pages is explicitly enabled: go to **Settings → Pages** and confirm a source branch/folder is selected.
  - Check that the `CNAME` file exactly matches the domain (no `https://`, no trailing slash, no extra whitespace).
  - Test both your custom domain and the github.io URL (https://username.github.io/repo-name/) to isolate issues:
    * If github.io works but custom domain doesn't → DNS/configuration issue
    * If neither works → GitHub Pages not enabled or repo issues
- **DNS not resolving**: Double‑check A record values and that you’ve waited for propagation (can take minutes to 24 hours). Use `nslookup yourdomain.com` or an online DNS checker like dnschecker.org.
- **File upload blocked by agent**: If you need to add `.html` files via the agent’s file tool and they’re rejected, rename them to `.txt` locally, add to repo, then rename back after `git add` (git tracks the rename). Or simply add them via local git clone/push.

## Evolution Notes
- This skill can be extended to support subdomains, HTTPS enforcement (GitHub Pages provides automatic HTTPS for custom domains), or integration with CI/CD workflows (e.g., using GitHub Actions to rebuild a static site before pushing).
- If you frequently need to create many such sites, consider turning the above steps into a reusable script or a GitHub Template repo.

---
**Done!** Your static site is now live on your custom domain via GitHub Pages.