How To Deploy A Static Website From GitHub To A Custom Domain

A site can work at its GitHub address and still fail after you connect a domain. I handle how to deploy a static website from GitHub to a custom domain as three jobs: publish the files, route the DNS, and secure the final address. That order makes failures easier to diagnose.

GitHub Pages hosts HTML, CSS, and JavaScript from a repository. It can also publish files produced by a supported build process.

What You Need Before Deploying a GitHub Pages Site

You need a GitHub repository, a domain you control, DNS access, and repository administrator permission. Put the finished website files in the folder you plan to publish. Name the homepage index.html.

Check every asset path before deployment. GitHub hosting is case-sensitive, so Logo.png and logo.png are different files.

GitHub Pages does not execute PHP, Python, or other server-side code. A database-powered form therefore needs separate backend hosting. See how to connect an HTML form to a MySQL database using PHP for that server-side workflow.

Step 1: Prepare the Static Website Repository

Create a repository and upload your HTML, CSS, JavaScript, images, and fonts to the main branch. Confirm that index.html appears in the intended publishing folder.

Test the website locally before publishing it. Open every page and verify that navigation, images, stylesheets, scripts, and downloadable files work correctly.

Choose Branch Deployment or GitHub Actions

I use branch deployment for plain static websites. GitHub can publish from any branch using either its root or /docs folder. New pushes to that source trigger another deployment.

Use GitHub Actions when a framework must build the final files first. This is common with React, Vue, Astro, and other static-site generators. GitHub recommends a custom workflow when direct branch publishing cannot handle the required build process.

Never publish source files when the browser needs the compiled output. Check whether your framework creates a dist, build, or similar production folder.

Step 2: Publish the Website With GitHub Pages

Open the repository and select Settings > Pages. Under Build and deployment, choose Deploy from a branch.

Select main, choose /(root) or /docs, and save the settings. GitHub will start a Pages deployment from the selected location.

Open the generated github.io address before editing DNS. This test is essential when learning how to deploy a static website from GitHub to a custom domain. A custom domain cannot repair a broken Pages deployment.

A 404 at this stage usually points to the wrong branch, a missing folder, or an incorrectly named homepage. The selected source branch must also exist before GitHub can publish it.

Review the latest Pages workflow run if the site does not appear. Its logs can reveal missing files or build failures.

Step 3: Choose the Preferred Domain Version

An apex domain is the bare address, such as example.com. A subdomain includes an additional label, such as www.example.com or portfolio.example.com.

I configure both the apex and www versions, then select one as the preferred custom domain. GitHub Pages can redirect between them when both have valid DNS records.

GitHub recommends adding the www version alongside an apex domain for HTTPS-secured websites.

Point the www CNAME directly to USERNAME.github.io. Do not point it to the apex domain. GitHub warns that routing a custom subdomain through the apex may interfere with HTTPS and site access.

Step 4: Add the Custom Domain in GitHub

Return to Settings > Pages. Enter the preferred address under Custom domain and click save.

Complete this step before changing the DNS. GitHub recommends adding the domain to the Pages website first because configuring DNS prematurely can create a subdomain-takeover risk.

GitHub also lets users and organizations verify domain ownership. The process adds a unique TXT record to the domain’s DNS configuration. Keep that TXT record in place after verification.

With branch publishing, GitHub automatically adds a CNAME file to the source branch. Custom GitHub Actions workflows instead use the domain saved in repository settings. An existing CNAME file is ignored in that workflow.

Step 5: Add the Correct GitHub Pages DNS Records

For an apex domain, create four A records with the host or name set to @:

• 185.199.108.153
• 185.199.109.153
• 185.199.110.153
• 185.199.111.153

For the www version, create a CNAME record. Set the host to www and the destination to USERNAME.github.io.

Do not include the repository name in the CNAME destination.

GitHub also supports AAAA, ALIAS, or ANAME records when the DNS provider offers them. Remove conflicting default records before continuing. Avoid wildcard DNS records such as *.example.com, which GitHub warns can create domain-takeover risks.

Consider an account named alexdev using alexportfolio.com. Its apex domain would point to the four GitHub IP addresses. Its www CNAME would point to alexdev.github.io, not alexdev.github.io/portfolio.

That distinction prevents a common error in how to deploy a static website from GitHub to a custom domain: treating a DNS destination like a complete browser URL.

Step 6: Check DNS and Enable HTTPS

DNS changes are not always immediate. GitHub states that propagation can take up to 24 hours. Avoid repeatedly deleting and recreating correct records while they are still propagating.

Use dig on macOS or Linux to inspect the returned DNS records. Windows users can run Resolve-DnsName from PowerShell.

After GitHub’s DNS check passes, enable Enforce HTTPS in the Pages settings. GitHub automatically requests a TLS certificate after successful DNS validation. The HTTPS option may take up to 24 hours to become available.

Open both versions of the domain. Confirm that one redirects to the preferred address and that the browser displays a secure connection.

My Three-Layer Deployment Test

My practical method for how to deploy a static website from GitHub to a custom domain checks three layers in a fixed order.

First, I open the original github.io address. This proves that the repository, source branch, and published files work.

Second, I inspect the apex and www DNS records separately. This proves that both addresses reach GitHub’s infrastructure.

Third, I test HTTPS, redirects, navigation, images, CSS, and JavaScript in a private browser window. Private browsing reduces confusion caused by cached DNS responses or old redirects.

This test narrows the problem quickly. A broken GitHub address signals a repository or build issue. A working GitHub address with a dead custom domain signals DNS. A certificate warning points toward TLS, conflicting records, CAA restrictions, or incomplete propagation.

Common Custom-Domain Problems

The Site Returns a 404

Check the selected branch, publishing folder, index.html, and CNAME destination. The CNAME should point to USERNAME.github.io without a repository path.

HTTPS Is Missing

Remove unrelated apex and subdomain records. Conflicting A, AAAA, ALIAS, ANAME, or CNAME records can prevent certificate generation.

Domains using CAA records must allow letsencrypt.org, because GitHub Pages uses Let’s Encrypt for its TLS certificates.

CSS or Images Disappear

Check filename capitalization and relative paths. A page may load while its assets return 404 errors.

Replace hard-coded http:// asset addresses with HTTPS or relative URLs. Otherwise, browsers may block them as mixed content after HTTPS is enabled.

A Build Removes the Domain

For branch publishing, preserve the generated CNAME file in the published source. Pull GitHub’s CNAME commit before running another local build.

For GitHub Actions deployment, manage the custom domain through Pages settings instead of relying on a CNAME file.

Your Domain Is Live—Stop Poking the DNS

The reliable answer to how to deploy a static website from GitHub to a custom domain is simple: publish first, add the domain in GitHub, configure only the required DNS records, and enable HTTPS after validation.

Make one small content change and push it to the publishing branch. If that update reaches the custom domain, your deployment pipeline is ready for future edits.

Then leave the DNS settings alone unless GitHub reports a specific configuration problem.

Frequently Asked Questions

1. How long does a GitHub Pages custom domain take?

DNS changes can take up to 24 hours, while HTTPS may become available sooner after successful validation.

2. Can I connect a GoDaddy or Namecheap domain?

Yes. Any US or international registrar can work if its DNS panel supports the required records.

3. Is a CNAME file always required?

Branch publishing uses one, while custom Actions deployments rely on the domain saved in GitHub Pages settings.

4. Can GitHub Pages run a PHP contact form?

No. GitHub Pages serves static files, so PHP and database processing require separate server-side hosting.