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, 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:

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.


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, create a CNAME record pointing to your User Page subdomain, This allows the DNS to automatically adjust if the server's IP is changed on GitHub.

dig +nostats +nocomments +nocmd
# ;                     IN      A
#              3592    IN      CNAME
#           43192   IN      CNAME
#                 22      IN      A

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 If your DNS provider supports this, it will allow us to provide the full benefits of our Content Delivery Network to your Page.

dig +nostats +nocomments +nocmd     3600    IN A

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

If you are using an apex domain ( instead of a subdomain ( 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:,

dig +nostats +nocomments +nocmd
;   73  IN  A   73  IN  A

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:

  • for User Pages
  • for top-level domains
  • 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 will not be redirected to a project's custom domain.

Real World Examples

Custom domain for User Pages redirects to redirects to The custom domain is defined in this file.

Custom domain for Project Pages is available at The custom domain is defined in this file.


For help troubleshooting a custom domain, see this guide.