How to Deploy a GitHub Pages Site with the gh CLI

This guide walks through taking a folder of HTML files from your machine to a live public URL using the GitHub CLI (gh). No web interface needed.

Step 1 — Install the GitHub CLI

If you don't have gh installed, use Homebrew:

brew install gh

Then authenticate:

gh auth login

Follow the browser prompt to complete login.

From inside your project folder:

git init
git add .
git commit -m "Initial commit"

This creates a public repo, sets it as the remote, and pushes in one command:

gh repo create my-repo-name --public --source=. --push

Replace my-repo-name with whatever you want the repo to be called. Your site will live at https://yourusername.github.io/my-repo-name/.

GitHub Pages serves index.html as the default. If your main page has a different name, rename it and push:

git mv your-page.html index.html
git commit -m "Rename to index.html"
git push

Tell GitHub to serve your repo as a website:

gh api repos/OWNER/REPO/pages \
  --method POST \
  --field source[branch]=master \
  --field source[path]=/

Replace OWNER with your GitHub username and REPO with your repo name.

It takes a minute or two to deploy. Your site will be live at https://OWNER.github.io/REPO/.

Add a CNAME record in your DNS registrar:

Type:  CNAME
Host:  subdomain
Value: OWNER.github.io

Then add a CNAME file to your repo with just the domain on one line:

echo "subdomain.yourdomain.com" > CNAME
git add CNAME
git commit -m "Add custom domain"
git push

Finally, set the custom domain in GitHub Pages settings:

gh api repos/OWNER/REPO/pages \
  --method PUT \
  --field cname=subdomain.yourdomain.com

You now have a live static site with a public URL. Every future change is a git push away.