GitHub Pages allows you to direct a domain name of your choice at your Page.
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
CNAMEin the root of your Page repository
Put the domain (or subdomain) into the 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.
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.
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 22.214.171.124
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 126.96.36.199
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.
A records which point to the following IP addresses:
dig example.com +nostats +nocomments +nocmd ;example.com example.com. 73 IN A 188.8.131.52 example.com. 73 IN A 184.108.40.206
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.
When you set up a custom domain, the server will automatically create a few redirects for you:
example.comfor User Pages
example.comfor top-level domains
wwwsubdomain is used
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.
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.
For help troubleshooting a custom domain, see this guide.