DEV Community

Cover image for GitHub Pages: A Beginner's Guide to Deploying Your Website on a Custom Domain
π™‰π™šπ™¨π™¨π™– 𝙆𝙀𝙙𝙀
π™‰π™šπ™¨π™¨π™– 𝙆𝙀𝙙𝙀

Posted on • Edited on

GitHub Pages: A Beginner's Guide to Deploying Your Website on a Custom Domain

#github #development #webdev #softwareengineering

This is the practical flow: publish your site on GitHub Pages, point your domain at it, then connect the domain inside GitHub.

If you are using Hostinger, the DNS screens will look a little different, but the idea stays the same.

Step 0: Decide what kind of Pages site you are deploying

You are basically choosing one of these:

  1. Project site
    URL starts as https://username.github.io/repo-name

  2. User site
    Repo is named username.github.io
    URL is https://username.github.io (no repo name in the URL)

Either option can use a custom domain. User site just looks cleaner by default.

Step 1: Publish using a gh-pages branch (only if you want branch based deploy)

You only need this if you are deploying from a branch (common for simple static sites, or when a tool outputs to a branch).

git checkout --orphan gh-pages
git reset --hard
git commit --allow-empty -m "Initialize gh-pages"
git push origin gh-pages
git checkout main
Enter fullscreen mode Exit fullscreen mode

Quick note: this creates an empty branch. You still need to actually put your built site files onto gh-pages (or configure your deploy tool to publish there).

If you are using GitHub Actions to build and deploy, you might skip the manual branch setup entirely.

Step 2: Turn on GitHub Pages in your repo

In your GitHub repo:

Settings β†’ Pages

Then choose your source:

  • Deploy from a branch β†’ select gh-pages and / (root) or
  • GitHub Actions if your framework uses a build step (React, Vite, Next static export, etc.)

Once it is enabled, GitHub will show your Pages URL.

Step 3: DNS setup in Hostinger (the part everyone overthinks)

Open Hostinger:

Domains β†’ your domain β†’ DNS / DNS Zone Editor

Before adding new records, remove any old ones that conflict:

  • Old A records pointing the root domain (@) somewhere else
  • Any existing CNAME for www that points somewhere else

What records you actually want

A records for the root domain (apex)

These point yourdomain.com (the @ host) to GitHub Pages:

Add four A records:

  • Name: @ β†’ 185.199.108.153
  • Name: @ β†’ 185.199.109.153
  • Name: @ β†’ 185.199.110.153
  • Name: @ β†’ 185.199.111.153

CNAME record for www

This points www.yourdomain.com to your GitHub Pages host:

  • Type: CNAME
  • Name: www
  • Points to: YOUR_GITHUB_USERNAME.github.io

That is it.

One important detail: a standard DNS setup does not use a CNAME for the root domain (@). Some providers support ALIAS or ANAME, but Hostinger typically expects the A records above for the apex.

Step 4: Connect the custom domain inside GitHub

Back in your GitHub repo:

Settings β†’ Pages β†’ Custom domain

Enter:

  • yourdomain.com

Save, then enable Enforce HTTPS once it becomes available.

GitHub will create or update a CNAME file in your published site automatically.

If you are using a framework build (React, Vite, etc.)

You usually need to make sure the CNAME makes it into the deployed output.

Depending on your setup, one of these is correct:

Option A: public/CNAME (common for React)

Create a file:

public/CNAME

Contents:

yourdomain.com
Enter fullscreen mode Exit fullscreen mode

Option B: docs/CNAME (only if you deploy from /docs)

Only do this if you specifically configured Pages to deploy from the docs folder.

Troubleshooting checklist

DNS changes are not showing up

DNS can take a while to propagate. If GitHub says it cannot verify, it is usually just time.

www works but the root domain does not

That means your www CNAME is fine, but your @ A records are missing or wrong.

HTTPS will not enable

Usually this is because the DNS is not stable yet, or you still have conflicting records. Recheck that:

  • @ has four A records to GitHub IPs
  • www has one CNAME to username.github.io
  • No extra conflicting A or CNAME records are hanging around

React app loads but routing breaks on refresh

That is not DNS, it is client side routing. You will need a SPA redirect strategy (commonly a 404.html that redirects to index.html) if you are using React Router.

Wrap

Once DNS is set and GitHub verifies the domain, your site should be live at:

https://yourdomain.com

If you want, tell me which stack you are deploying (plain HTML, React, Vite, Next export) and whether you are deploying from a branch or Actions, and I will tighten this into the exact steps for your repo with zero extra noise.

Love,
NESSA KODO

Top comments (0)