Domain Mapping to GitHub

A Records vs. CNAME Records

When you are mapping a domain on GitHub Pages (or on any site really) an important concept to understand is the difference between A Records and CNAME Records. The following definition comes from DNS Simple:

The A record points a name to a specific IP. For example, if you want blog.dnsimple.com to point to the server 185.31.17.133 you will configure:

blog.dnsimple.com. A 185.31.17.133

The CNAME record points a name to another name, instead of an IP. The CNAME source represents an alias for the target name and inherits its entire resolution chain. Let’s take our blog as example:

blog.dnsimple.com.      CNAME   aetrion.github.io.
aetrion.github.io. CNAME github.map.fastly.net. github.map.fastly.net. A 185.31.17.133

We use GitHub Pages, and we set blog.dnsimple.com as a CNAME of aetrion.github.io, which is a CNAME of github.map.fastly.net, which is an A record pointing to 185.31.17.133. This means blog.dnsimple.com resolves to 185.31.17.133.

To summarize, an A record points a name to an IP. A CNAME record can point a name to another CNAME.

It’s good practice to point domains using CNAME records when possible because IP addresses can change, and when they do an A Record will break because it is hardcoded. You might think of CNAME records as relative hostnames; this way, the IP address can change regularly but the mapped domain will not break.

One issue is that root domains (sometimes called “zone apex” or “naked domain”) have to be set up as an A record, not a CNAME. This means that with most DNS providers you can setup a subdomain CNAME (githubdemo.pilotirwin.com) to point to a service like GitHub, but you cannot setup your root domain (pilotirwin.com) as a CNAME. That root domain would have to be an A record.

Mapping your Domain on GitHub

You can use CNAME Records or A Records to map your custom domain to GitHub. Mapping a subdomain using a CNAME record is recommended so the domain doesn’t break if the server IP changes, which may very well happen. That said, sometimes you just need that root domain mapped, so an A Record will suffice.

GitHub provides a good overview of using custom domains on GitHub in their guide, "About custom domains and GitHub Pages."

Mapping your Root Domain with A Records

This example will show how to map the root domain pilotirwin.com onto a GitHub Page. First you'll need to make sure your GitHub Pages site is set up and prepared for the new domain, so that your domain will be able to connect to it.  To do this, see GitHub’s "Managing a custom domain for your GitHub Pages site: Configuring an apex domain."

You will complete steps 1-4 in the settings for your GitHub Pages site's repository. For consistency's sake, we'll share those steps below here as well:

Github's Steps 1-4:
  1. On GitHub, navigate to your site's repository.

  2. Under your repository name, click Settings.

  3. In the "Code and automation" section of the sidebar, click Pages.

  4. Under "Custom domain", type your custom domain, then click Save. If you are publishing your site from a branch, this will create a commit that adds a CNAME file to the root of your source branch. If you are publishing your site with a custom GitHub Actions workflow , no CNAME file is created. For more information about your publishing source, see "Configuring a publishing source for your GitHub Pages site."

You'll know you're ready to go when the DNS check for your custom domain comes back successful.

GitHub_Mapping_-_Successful_DNS_Check.png

This screenshot uses a subdomain as an example, but the settings are controlled in the same place and the DNS check will work the same way.

Once you've completed the starting configuration steps in GitHub, which will be through step 4, you'll need to find the DNS Zone Editor under the Domains section in cPanel.

GitHub_Mapping_-_Zone_Editor.png

After that you need to choose the root domain you will be mapping, and locate the tools for managing its A Records.

GitHub_Mapping_-_A_Record_Tools.png

If A Records already exist for this domain, which you can check using the "Manage" tool, you may need to delete them in order to prevent conflicts. We recommend always taking a screenshot or otherwise recording the contents of any records before you delete them, in case you need to undo your work for any reason.

Once you select the domain, you need to create two A Records for it using the below screenshot as a template. The Name field will hold the domain you are trying to map, and the Address field will hold the IP you want to map the domain to. GitHub has two separate IP addresses you'll need to map the domain to, 192.30.252.153 and 192.30.252.154, so you will need to create a separate A Record for each one.

GitHub_Mapping_-_Setting_A_Records.png

Once you have created both A Records in the DNS Zone Editor you should be all set.

If you run into issues, you can always refer back to GitHub's own guide, “Managing a custom domain for your GitHub Pages site: Configuring an apex domain." You can also see GitHub’s “Troubleshooting custom domains and GitHub Pages” or contact our Support team. Remember also that DNS changes can take up to 24 hours to fully propagate.

Mapping your Subdomain with CNAME Records

This example will map the subdomain githubdemo.pilotirwin.com onto a GitHub Pages Repository, capnpilot.github.io/tempdemo, using a CNAME Record.

First you'll need to make sure your GitHub Pages site is set up, so that your subdomain will be able to connect to it. To do this, see GitHub’s “Managing a custom domain for your GitHub Pages site: Configuring a subdomain.”

Like above, you will complete steps 1-4 in the settings for your GitHub Pages site's repository. You'll know you're ready to go when the DNS check for your custom domain comes back successful.

GitHub_Mapping_-_Successful_DNS_Check.png

After you've completed the starting configuration steps in GitHub, go to the DNS Zone Editor in the Domains section of cPanel.

GitHub_Mapping_-_Zone_Editor.png

Note: In the above screenshot, you will see that the Domains section in cPanel also includes a tool called Subdomains. This tool is useful if you want to set up a site in a subdomain that is hosted on your cPanel. It will generate a subdomain with a full set of pre-existing records, including A Records that point the subdomain towards your cPanel. These A Records will cause conflict with the CNAME record you are trying to set up, so if you want to generate a subdomain that you intend to point elsewhere with a CNAME, you shouldn't use the Subdomain tool.

Once you've reached the Zone Editor, select Manage. This will take you to a place where you can manage all existing records, as well as create new ones.

GitHub_Mapping_-_Managing_All_Records.png

Find the tool marked Add Record, then select Add "CNAME" Record.

GitHub_Mapping_-_Add_New_Record.png

Then you can create a new subdomain that only uses a CNAME record, and point it to the place it needs to go. Put the name of the subdomain in the Name field, and the URL of your GitHub account in the Record field, then save the record.

GitHub_Mapping_-_Creating_New_CNAME_Record.png

After that you should be set. Even if your repository is located at capnpilot.github.io/tempdemo, like the one in this example, you only need capnpilot.github.io in the CNAME field. This is because when you originally set the domain settings in GitHub, you did this in the settings for the repository that's located in the subdirectory (here, that would be the settings for capnpilot.github.io/tempdemo).

If you run into issues, you can always refer back to GitHub's guide, “Managing a custom domain for your GitHub Pages site: Configuring a subdomain.” You can also see GitHub’s “Troubleshooting custom domains and GitHub Pages” or contact our Support team. Remember also that DNS changes can take up to 24 hours to fully propagate.

Managing SSL & HTTPS for your GitHub Pages Domain

SSL certificates for domains pointed to GitHub Pages aren't provisioned through cPanel, but through GitHub. GitHub has more information in their guide, "Securing your GitHub Pages site with HTTPS". What follows is a quick summary, but you can refer to that guide if you need more details.

SSL Certificates

When you set up a custom domain in GitHub Pages, an automatic DNS check triggers which determines if your DNS is set to allow GitHub Pages to automatically obtain a certificate. If the check is successful, GitHub will queue a job to request a TLS certificate from LetsEncrypt. When it receives the certificate, it'll upload it automatically and display a checkmark next to your custom domain name.

Forcing HTTPS

You can force HTTPS on your site by navigating to your site's repository, then going to Settings > Code and automation > Pages > GitHub Pages. In the GitHub Pages section, you'll be able to select Enforce HTTPS.

GitHub_Mapping_-_Forcing_HTTPS.png

GitHub also has documentation for this available in their guide, "Securing your GitHub Pages site with HTTPS: Enforcing HTTPS for your GitHub Pages site."

Was this article helpful?
0 out of 0 found this helpful

Articles in this section

See more
Reclaim Hosting Support Hours
8:00 am - 5:00 pm ET, Monday through Friday
Submit a Ticket
Get a quick and helpful response from the pros.
Need Extra Support?
No problem, we're here to help! Talk to us about Professional Services.