4  Adding a Custom Domain

Customizing your domain name can be a complicated process. The full GitHub instructions can be found here.

These instructions assume that you already have ownership of the custom domain that you would like to use, as well as knowledge about your specific DNS provider.

  1. Go to your GitHub repository
  2. Click Settings
  3. In the left-hand menu bar, select Pages
  4. Scroll down to the Custom Domain section
  5. Enter your custom domain in the textbox. For example, you should write: mysite.com
  6. Hit Save
  7. Navigate to your DNS provider and create a CNAME record that points your subdomain to the default domain for your site.
    1. Example: if you want to use www.example.com, you will create a CNAME record that points www.example.com to <username>.github.io. Note that this is the user page, not a repository name.
    2. Instructions for creating a CNAME record vary by DNS provider. GitHub recommends using your DNS provider’s documentation .
    3. For example, on GoDaddy, when you add a record, the record name would be “www” and the record value would be “username.github.io”
  8. To ensure that your apex domain (i.e. without “www”) works, you should also include four A records in your DNS provider’s web console. For example, on GoDaddy, the name would be the @ symbol and the values would be the following:
    • 185.199.108.153
    • 185.199.109.153
    • 185.199.110.153
    • 185.199.111.153
  9. Confirm that your DNS record is configured correctly using the terminal.
    1. In the terminal, type: dig WWW.EXAMPLE.COM +nostats +nocomments +nocmd where WWW.EXAMPLE.COM should be replaced with your custom domain name.
    2. You should see the GitHub pages link in the output.
    3. This can take some time to propogate. For example, on GoDaddy, you can set your “TTL” (time to live) as low as 600 seconds. However, GoDaddy also warns that changes may not take effect for up to 48 hours. We also suggest checking your site (and all variations of your site link, e.g., with and without “www”) on an incognito window, as your browser’s cache can sometimes make it appear as if your site did not update.
  10. Go back to your GitHub repository.
  11. Go to Settings > Pages > Custom domain
  12. Check off Enforce HTTPS
    • If this says something along the lines of “Your domain is not properly configured to support HTTPS” we will need to add additional records with your DNS provider
    • We strongly recommend following instructions from your DNS provider. You should look up “HTTPS record for [your DNS provider]” in Google and follow any of their documentation.
    • For example, on GoDaddy, you can add an HTTPS record where the name is @ and the value is your site’s domain (e.g., mysite.com)
  13. If you run into any additional problems, you may want to ensure that there are no additional A records aside from the ones listed above. This may be a problem if you have previously had your site hosted through a service separate from GitHub pages.
  14. Some common warning messages that you may see when GitHub pages is connecting to your site include “DNS valid for primary” or “DNS check in progress” – these are both OK, and should go away once your site is connected.
  15. On the other hand, if you get an error message “DNS check unsuccessful” or “Both your custom domain and its alternative name are improperly configured,” then it means either your A or CNAME records are incorrect. Please check these!