GitHub Pages allows you to direct a domain name of your choice at your Page.

Setting the domain in your repo

Let's say you own the domain example.com, and you would like to use it for your Pages. Telling the GitHub server to serve from this domain is easy:

  • Create a file named CNAME in the root of your Page repository
  • Put the domain (or subdomain) into the CNAME file:

    example.com

If you are working with a User Page repository, the CNAME file should go in the master branch. If you're working with a Project Page, then it should go in the gh-pages branch of the project repository.

Tip: After creating the CNAME file, it can take up to 10 minutes for the content to become available. Once the Page content is available, you can continue to make the DNS changes in the next step. If the Page doesn't build successfully, you'll receive a notification from GitHub.

You can only have one custom domain for any given set of Pages. If you want multiple domains to point to the same Pages, you will need to use a service that can redirect the other domains to your Pages domain.

Setting up DNS

Next, you need to set up your DNS. Remember that it may take up to a full day for DNS changes to propagate.

There are two ways to set up your DNS, depending on what type of domain you're using.

Subdomains

This is the recommended way of setting up a Page using a custom domain. This method gives your Page the benefit of our Content Delivery Network and Denial of Service protection.

When working with a subdomain, like www.example.com, create a CNAME record pointing www.example.com to your User Page subdomain, username.github.io. This allows the DNS to automatically adjust if the server's IP is changed on GitHub.

dig www.example.com +nostats +nocomments +nocmd
# ;www.example.com.                     IN      A
# www.example.com.              3592    IN      CNAME   username.github.io.
# username.github.io.           43192   IN      CNAME   github.map.fastly.net.
# github.map.fastly.net.                 22      IN      A       199.27.76.133

Apex Domains

Warning: DNS A records require that the IP address is hardcoded to your application's service. This prevents GitHub from dynamically managing traffic when adverse conditions arise.

Some DNS providers (like DNSimple) allow you to use an ALIAS record to point your custom apex domain to username.github.io. If your DNS provider supports this, it will allow us to provide the full benefits of our Content Delivery Network to your Page.

dig example.com +nostats +nocomments +nocmd
example.com.     3600    IN A     199.27.73.133

NOTE: It's OK if you get a different IP address. Use dig username.github.io to see the full resolution path.

If you are using an apex domain (example.com) instead of a subdomain (www.example.com) and your DNS provider does not support ALIAS records, then your only option is to use A records for your DNS. This will not give you the benefit of our Content Delivery Network.

Create DNS A records which point to the following IP addresses: 192.30.252.153, 192.30.252.154.

dig example.com +nostats +nocomments +nocmd
;example.com
example.com.   73  IN  A 192.30.252.153
example.com.   73  IN  A 192.30.252.154

Warning: You should not use a CNAME record with an apex domain, as this may cause issues with other services on the apex domain, like email.

Automatic redirects

When you set up a custom domain, the server will automatically create a few redirects for you:

  • username.github.ioexample.com for User Pages
  • www.example.comexample.com for top-level domains
  • example.comwww.example.com if the www subdomain is used

For the www ⇔ TLD redirects to work, both the TLD and www subdomain DNS records must be pointed to the Pages server.

A custom domain on User or Organization Pages will apply the same domain redirect to all Project Pages hosted under that account.

Apex domain redirects to subdomains

If you use a custom subdomain but would still like to have your custom apex domain point to your active Page, domain redirection is a viable alternative. Most DNS providers offer domain redirection, sometimes called domain forwarding.

Warning: Project Pages subpaths like http://username.github.io/projectname will not be redirected to a project's custom domain.

Real World Examples

Custom domain for User Pages

atmos.github.io redirects to atmos.org. atmos.github.io/warden-github redirects to atmos.org/warden-github. The custom domain is defined in this file.

Custom domain for Project Pages

muan.github.io/emoji is available at emoji.muan.co. The custom domain is defined in this file.

Troubleshooting

For help troubleshooting a custom domain, see this guide.