Introduction

GitHub Pages is a convenient way to host static websites directly from a GitHub repository. It is particularly useful for portfolios, documentation sites, project pages, and other frontend applications that do not require a traditional server.

However, the default GitHub Pages URL is not always ideal for a professional website. A custom domain provides a cleaner public identity while allowing the underlying website to remain hosted on GitHub Pages.

This guide explains how to connect a custom domain to an existing GitHub Pages website using DNS records. The examples intentionally use placeholder domains and usernames so that private account information is not exposed.

Security note: Never publish registrar login details, verification links, account identifiers, API tokens, passwords, private repository information, or personal contact information in a public blog post. The DNS values required by GitHub Pages are public and are safe to document.

1. Understand the Architecture

A custom domain does not replace GitHub Pages. Instead, DNS tells browsers where the domain should resolve.

The overall setup looks like this:

User
  │
  ▼
Custom Domain
example.com
  │
  │ DNS lookup
  ▼
GitHub Pages
USERNAME.github.io
  │
  ▼
GitHub Repository
  │
  ▼
Static Website

The domain registrar manages the domain and DNS records, while GitHub Pages continues to serve the website.

For a typical setup:

The apex/root domain is example.com.
The www subdomain is www.example.com.
The apex domain uses GitHub Pages A records.
The www subdomain uses a CNAME record pointing to the GitHub Pages hostname.

2. Before Changing DNS

Before modifying DNS records, identify these three pieces of information:

Custom domain:
example.com

GitHub Pages domain:
USERNAME.github.io

DNS provider:
Your domain registrar or DNS hosting provider

The GitHub Pages hostname should be the default hostname associated with the GitHub Pages site.

Do not use a repository URL such as:

USERNAME.github.io/repository-name

for the CNAME value.

The CNAME should point to the GitHub Pages hostname itself.

3. Configure the Custom Domain in GitHub

Open the GitHub repository that contains the website.

Navigate to:

Repository
    → Settings
        → Pages
            → Custom domain

Enter the custom domain:

example.com

and save it.

GitHub Pages can use both an apex domain and a www subdomain. Configuring both is useful because visitors may enter either version.

GitHub may create or update a CNAME file in the repository depending on the deployment configuration.

If the website is deployed through GitHub Actions, the custom-domain configuration can also be managed through the deployment workflow.

4. Configure the Apex Domain with A Records

For an apex domain such as:

example.com

GitHub Pages provides four IPv4 addresses.

For more information, see Managing a custom domain for your GitHub Pages site.

Create these A records:

Type	Name	Value
A	`@`	`185.199.108.153`
A	`@`	`185.199.109.153`
A	`@`	`185.199.110.153`
A	`@`	`185.199.111.153`

The @ symbol represents the root/apex domain.

For example:

A    @    185.199.108.153
A    @    185.199.109.153
A    @    185.199.110.153
A    @    185.199.111.153

GitHub's current documentation also lists IPv6 AAAA records. They can be configured when IPv6 support is required, but the four IPv4 A records are the straightforward configuration for a standard GitHub Pages setup.

Important

If your DNS provider has automatically created an A record such as:

A    @    Parked

or another hosting/parking IP, it should not remain alongside the GitHub Pages configuration for the apex domain.

Extra conflicting A or AAAA records can cause incorrect routing and may interfere with HTTPS certificate provisioning.

5. Configure the `www` Subdomain

The www version should point to the GitHub Pages hostname using a CNAME record.

Create or update:

Type:  CNAME
Name:  www
Value: USERNAME.github.io

For example:

CNAME    www    USERNAME.github.io

Do not point the CNAME to an IP address.

A CNAME maps one hostname to another hostname, whereas an A record maps a hostname to an IPv4 address.

Also avoid creating multiple conflicting CNAME records for the same hostname.

6. What to Keep and What to Replace

A common DNS zone may contain several records that are unrelated to website hosting.

For example:

A       @       Parked
NS      @       nsXX.domaincontrol.com
NS      @       nsYY.domaincontrol.com
CNAME   www     example.com
CNAME   _domainconnect   ...
SOA     @       ...
TXT     _dmarc  ...

For a GitHub Pages website:

Replace

A       @       Parked

with the GitHub Pages A records.

Also replace an incorrect www CNAME such as:

CNAME   www     example.com

with:

CNAME   www     USERNAME.github.io

Usually leave unchanged

Records such as:

NS
SOA
_dmarc
_domainconnect

should not be deleted simply because they are unrelated to GitHub Pages.

In particular, default nameserver records are managed by the DNS provider when the domain uses that provider's nameservers.

Rule: Do not delete DNS records unless you understand what service uses them.

This is especially important for MX, TXT, CAA, and other records that may control email, domain verification, or certificate issuance.

7. Domain Verification Can Block DNS Changes

Newly registered domains may require registrant contact or WHOIS verification.

A registrar may display a warning such as:

Your domain is pending verification. Some domain actions are unavailable until your domain verification is complete.

If DNS editing is disabled, do not assume that the DNS configuration is broken.

First complete the domain verification process provided by the registrar.

Typical steps are:

Domain registration
       │
       ▼
Verification email
       │
       ▼
Verify registrant information
       │
       ▼
Domain becomes verified
       │
       ▼
DNS management becomes available

The exact verification process depends on the registrar and the domain's registration status.

Do not publish the verification email, verification URL, or personal registrant information in a public article.

8. DNS Propagation

DNS changes are not necessarily visible everywhere immediately.

After changing the records, some DNS resolvers may continue returning the previous values until their cached records expire.

A typical workflow is:

DNS record changed
       │
       ▼
Authoritative DNS updated
       │
       ▼
Resolvers refresh their cached data
       │
       ▼
Visitors begin receiving the new destination

Depending on the DNS provider, TTL, and resolver cache, changes can take from minutes to considerably longer to become visible globally.

Do not repeatedly change the records simply because the website does not update immediately.

9. Verify DNS from the Command Line

The dig utility can be used to inspect DNS records.

For the apex domain:

dig example.com +noall +answer -t A

The response should contain the four GitHub Pages addresses:

example.com.    3600    IN    A    185.199.108.153
example.com.    3600    IN    A    185.199.109.153
example.com.    3600    IN    A    185.199.110.153
example.com.    3600    IN    A    185.199.111.153

To check the www record:

dig www.example.com +noall +answer -t CNAME

The result should point to:

USERNAME.github.io

These commands are useful because they allow you to inspect the DNS response independently of the registrar's dashboard.

10. Enable HTTPS

After GitHub detects the custom-domain configuration, GitHub Pages can provision an HTTPS certificate.

In:

Repository
    → Settings
        → Pages

look for the HTTPS option.

Once the certificate is available, enable:

Enforce HTTPS

Your final website should be accessible through:

https://example.com

and, if configured:

https://www.example.com

HTTPS is not just a visual improvement. It protects traffic between the visitor and the website and is expected for modern production websites.

11. Common Mistakes

Mistake 1: Keeping the parking A record

Incorrect:

A    @    Parked
A    @    185.199.108.153

The parking record should be removed or replaced when the domain is being served through GitHub Pages.

Mistake 2: Pointing `www` to the apex domain

Incorrect:

CNAME    www    example.com

For GitHub Pages, use:

CNAME    www    USERNAME.github.io

Mistake 3: Adding a CNAME to the apex domain

Do not attempt:

CNAME    @    USERNAME.github.io

when using the standard GitHub Pages A-record configuration.

Use:

A    @    185.199.108.153
A    @    185.199.109.153
A    @    185.199.110.153
A    @    185.199.111.153

and use the CNAME for www.

Mistake 4: Changing nameservers unnecessarily

You generally do not need to change the domain's nameservers just to connect it to GitHub Pages.

If your registrar already manages the DNS zone, configure the required records there.

Changing nameservers unnecessarily can replace the entire DNS management system and may break unrelated services such as email.

Mistake 5: Deleting unrelated DNS records

Do not delete records simply because they are not part of GitHub Pages.

For example:

MX
TXT
CAA
_dmarc

may serve other purposes.

Review each record before changing it.

Mistake 6: Publishing sensitive configuration

A public tutorial should never contain:

Registrar username
Registrar password
2FA codes
Verification links
API tokens
Private repository URLs
Personal email addresses
Account IDs
Private IP addresses

Use placeholders instead:

example.com
USERNAME.github.io
your-email@example.com

Public GitHub Pages IP addresses are different: they are published by GitHub and are not secret.

12. Recommended Final Configuration

For a standard GitHub Pages deployment, the DNS configuration should conceptually look like this:

A       @       185.199.108.153
A       @       185.199.109.153
A       @       185.199.110.153
A       @       185.199.111.153

CNAME   www     USERNAME.github.io

Other DNS records required by unrelated services should remain in place.

The architecture is therefore:

                    ┌──────────────────────┐
                    │      Visitor         │
                    └──────────┬───────────┘
                               │
                               ▼
                    ┌──────────────────────┐
                    │   Custom Domain      │
                    │     example.com      │
                    └──────────┬───────────┘
                               │
                       DNS resolution
                               │
                ┌──────────────┴──────────────┐
                │                             │
                ▼                             ▼
        Apex A Records                  www CNAME
                │                             │
                └──────────────┬──────────────┘
                               ▼
                    ┌──────────────────────┐
                    │     GitHub Pages     │
                    └──────────┬───────────┘
                               ▼
                    ┌──────────────────────┐
                    │    GitHub Repository  │
                    └──────────────────────┘

Conclusion

Connecting a custom domain to GitHub Pages is primarily a DNS configuration task. The website itself can remain on GitHub Pages; the domain simply needs to resolve to GitHub's infrastructure.

The essential configuration is:

Configure the custom domain in GitHub Pages.
Point the apex domain to GitHub Pages using the required A records.
Point www to the GitHub Pages hostname using a CNAME.
Remove conflicting parking or hosting records.
Keep unrelated DNS records intact.
Complete domain verification if the registrar requires it.
Wait for DNS propagation.
Verify the DNS records.
Enable HTTPS once GitHub has provisioned the certificate.

The important lesson is that DNS changes should be made deliberately. A working website is not just about pointing the domain to the correct server; it also requires preserving the DNS records responsible for other services and avoiding conflicting records that can interfere with routing or HTTPS.

Introduction

1. Understand the Architecture

2. Before Changing DNS

3. Configure the Custom Domain in GitHub

4. Configure the Apex Domain with A Records

Important

5. Configure the `www` Subdomain

6. What to Keep and What to Replace

Replace

Usually leave unchanged

7. Domain Verification Can Block DNS Changes

8. DNS Propagation

9. Verify DNS from the Command Line

10. Enable HTTPS

11. Common Mistakes

Mistake 1: Keeping the parking A record

Mistake 2: Pointing `www` to the apex domain

Mistake 3: Adding a CNAME to the apex domain

Mistake 4: Changing nameservers unnecessarily

Mistake 5: Deleting unrelated DNS records

Mistake 6: Publishing sensitive configuration

12. Recommended Final Configuration

Conclusion

References

Web Development Articles

Connecting a Custom Domain to GitHub Pages: A Practical DNS Guide

Connecting a Custom Domain to GitHub Pages: A Practical DNS Guide