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:

blog.dnsimple.com. A 185.31.17.133

blog.dnsimple.com.      CNAME   aetrion.github.io.
aetrion.github.io.      CNAME   github.map.fastly.net.
github.map.fastly.net.  A       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:

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

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.

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

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.

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.

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

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.

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

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.

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 also has documentation for this available in their guide, "Securing your GitHub Pages site with HTTPS: Enforcing HTTPS for your GitHub Pages site."