Custom domain for GitHub project pages

Question

I have a gh-pages branch in one of my http://github.com repos. The GitHub project pages works fine if I go to http://myuser.github.com/myrepo

I want to setup a custom domain (myexample.com) that will serve up these project pages. I want both myexample.com and www.myexample.com to serve up these project pages.

GitHub pages help says to make an A record and a CNAME record in your DNS. The A record makes sense, but I do not know what CNAME record to make in my DNS.

The gh-pages docs say to make a CNAME record for 'charlie.github.com' which is a user page repository. I do not have a user page repository - I only have a project repository and a gh-pages branch that I want to use for myexample.com and www.myexample.com.

Do I need to make a user page repository just so I can use my project page for www.myexample.com and myexample.com?

I would just try it, but I want to make sure this will work as I already have www.myexample.com live and don't want to make a mistake.

I emailed GitHub support and their response was

You can't have both point to the same gh-pages as far as I know.

I find it hard to believe they would only support A records for project pages.

Has anyone successfully done this before?

Roundtheclock

I've set up lacewing-project.org with just an A record pointing to 207.97.227.245 (no CNAME records), and it works fine. I also put a file called CNAME in the root of the gh-pages branch containing the domain name. – Presignify

In my case, just placing the CNAME file in gh-pages branch did the trick, thank you! – Agan

Answer 1

1/23/19 UPDATE:

Things have changed quite a bit (for the better) since my last answer. This updated answer will show you how to configure:

1. Root apex (example.com)
2. Sub-domain (www.example.com)
3. HTTPS (optional but strongly encouraged)

In the end, all requests to example.com will be re-directed to https://www.example.com (or http:// if you choose NOT to use HTTPS). I always use www as my final landing. Why(1,2), is for another discussion.

This answer is long but it is not complicated. I was verbose for clarity as the GitHub docs on this topic are not clear or linear.

Step 1: Enable GitHub pages in GitHub settings

1. From your repo, click on the tab
2. Scroll down to the GitHub Pages section. You have two options:
3. Choosing master branch will treat /README.md as your web index.html. Choosing master branch /docs folder will treat /docs/README.md as your web index.html.
4. Choose a theme.
5. Wait a minute while GitHub publishes your site. Verify it works by clicking on the link next to Your site is ready to be published at

Step 2: Specify custom domain in GitHub settings

Enter your custom domain name here and hit save:

This is a subtle, but important step.

• If the custom domain you added to your GitHub Pages site is example.com, then www.example.com will redirect to example.com
• If the custom domain you added to your GitHub Pages site is www.example.com, then example.com will redirect to www.example.com.

As mentioned before, I recommend always landing at www so I entered www.example.com as pictured above.

Step 3: Create DNS entries

In your DNS provider's web console, create four A records and one CNAME.

1. A Records for @ (aka root apex):

Some DNS providers will have you specify @, others (like AWS Route 53) you will leave the sub-domain blank to indicate @. In either case, these are the A records to create:

185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

Check the Github docs to confirm these are the most up-to-date IPs.

2. Create a CNAME record to point www.example.com to YOUR-GITHUB-USERNAME.github.io.

This is the most confusing part.

Note the YOUR-GITHUB-USERNAME NOT the GitHub repo name! The value of YOUR-GITHUB-USERNAME is determined by this chart.

For a User pages site (most likely what you are), CNAME entry will be username.github.io, ex:

For a Organization pages site, CNAME entry will be orgname.github.io, ex:

Step 5: Confirm DNS entries

1. Confirm your A records by running dig +noall +answer example.com. It should return the four 185.x.x.x IP addresses you entered.

2. Confirm your CNAME record by running dig www.example.com +nostats +nocomments +nocmd. It should return a CNAME YOUR-GITHUB-USERNAME.github.io

It may take an hour or so for these DNS entries to resolve/propagate. Once they do, open up your browser to http://example.com and it should re-direct to http://www.example.com

Step 6: SSL (HTTPS) Configuration. Optional, but highly recommended

After you have the custom domain working, go back to the repo settings. If you already have the settings page open, hard refresh the page.

If there is a message under the Enforce HTTPS checkbox, stating that it is still processing you will need to wait. You may also need to hit the save button in the Custom domain section to kick off the Enforce HTTPS processing.

Once processing is completed, it should look like this:

Just click on the Enforce HTTPS checkbox, and point your browser to https://example.com. It should re-direct and open https://www.example.com

THATS IT!

GitHub will automatically keep your HTTPS cert up-to-date AND should handle the apex to www redirect over HTTPS.

Roundtheclock

As of Apr 19, 2012, GitHub's documentation uses 204.232.175.78 as the IP address. – Ploy

I am getting invalid hostname for 204.232.175.78 – Lovieloving

I think it's also okay to set up a CNAME that points www to the root. – Jerroldjerroll

Is it possible to set this up with a CNAME (no A record)? – Hurst

@Hurst I would think so, 204.232.175.78 resolves to pages.github.com - so you could give that a try. Curious - why u want CNAME? To insulate from pages IP changes. It has "changed" in the past , in that they just change their docs to a new IP (old still works) – Roundtheclock

Checked feb 6th 2014 and github docs say: Create DNS A records which point to the following IP addresses: 192.30.252.153, 192.30.252.154. – Algin

"If you are using an A record that points to 207.97.227.245 or 204.232.175.78, you will need to update your DNS settings, as we no longer serve Pages directly from those servers." help.github.com/articles/my-custom-domain-isn-t-working - 3/8/14 – Semipalatinsk

I don't think it's possible to set up a CNAME record from the naked @ domain. That's why you need the A records, to handle the redirect from the naked domain to the www subdomain. It's a problem with any cloudhost. No guarantee of a fixed IP. – Devitrify

@Devitrify you are correct, some DNS providers dont support alias at the root apex. I have edited my answer. FWIW if your DNS provider does support alias at the apex, that should be used instead. – Roundtheclock

@Roundtheclock I can convert as of today, this method still works perfectly. Thank you so much. – Conformance

@Roundtheclock GoDaddy doesn't allow @ and www to yourusername.github.io, only one CNAME record per subdomain :( – Lietuva

For Namecheap domain users, to set up only an apex domain name, do this in your All Host Records. – Saraann

I am facing the same problem. I deploy my site on GitHub pages and then just try to custom my domain which doesn't exit. But then when I open my website it will redirect to that custom domain. How would I delete that one. Help me what to do ? – Poitiers

Pass by Hamburg, and I'll buy you a beer. 🍻 – Vinosity

Services like "neubox" don't allow you to change A records or CNAME records. But you can request this via support. Send an email with correct ips and that's done. – Itin

The IPs that you must use can be checked from here: help.github.com/articles/troubleshooting-custom-domains/… – Squish

I've updated the answer to address and include info many of these comments bring up. Thanks for all the feedback! – Roundtheclock

If I am hosting a project at: https://vedantroy.github.io/my-repository-name/, should my CNAME record point to vedantroy.github.io or vedantroy.github.io/my-repository-name? Also Google Domains gives the option to name the CNAME domain. I just named it www. Do you know if this is correct? – Catchword

Thanks for these instructions. I followed precisely and the dig commands return the expected results. However, my apex domain is not working. So https://www.*.com works and https://*.github.io works but https://*.com gives an error "can't establish secure connection to server". Any ideas? – Eggcup

"GitHub will automatically keep your HTTPS cert up-to-date AND should handle the apex to www redirect over HTTPS" -- this results in a security warning as GH does not provide a valid certificate for the apex domain... – Bindle

Here's the missing bit: A hack that seems to trick GH's certbot so that it generates valid SSL certs for both the apex domain and www subdomain: https://mcmap.net/q/75078/-github-pages-https-www-redirect – Bindle

"Note the YOUR-GITHUB-USERNAME NOT the GitHub repo name! The value of YOUR-GITHUB-USERNAME is determined by this chart. " ERROR, in the line... what was inside? – Georama

This comment github.com/isaacs/github/issues/1675#issuecomment-611599506 suggests that redirecting the raw domain to www using a CNAME record is the best approach as of 2020. – Shibboleth

What if we already have a blog on github_username.github.io? which is my case – Yaker

One thing I suggest adding to step 5.1 - it's important that dig +noall +answer my_example_site.com returns ONLY those 4 entries. My problem was that there was an additional entry pointing to 34.102.136.180 that had been in the registry (GoDaddy) from the beginning. I got rid of it by removing the A @ Parked entry from the GoDaddy DNS manager: dcc.godaddy.com/manage/my_example_site.com/dns . It took around 15 minutes for this to propagate so that the dig command only saw the 4 IP's. – Standard

Complete answer and well updated as of March 2023. – Eon

One important point for GoDaddy users: Sometimes GoDaddy adds a default CNAME records with the value of your domain name. To enforce https you need to delete that record and add a new CNAME record as stated in part 2 of Step 3 of this answer. – Savoyard

As of 18 Jun 2023, I had all sorts of errors of misconfiguration in CNAME and etc... the site was live on the domain given but I could not enable forcing HTTPS. Adding WWW to the custom domain in GitHub just solved it all. – Heartburning

for the CNAME file at root of the repo, should it be www.example.com or just example.com? Should it match what you put in the custom domain box of the github pages settings and does it depend which redirect you want? – Characterize

Answer 2

Overview

The documentation is a little confusing when it comes to project pages, as opposed to user pages. It feels like you should have to do more, but actually the process is very easy.

It involves:

1. Setting up 2 static A records for the naked (no www) domain.
2. Creating one CNAME record for www which will point to a GitHub URL. This will handle www redirection for you.
3. Creating a file called CNAME (capitalised) in your project root on the gh-pages branch. This will tell Github what URL to respond to.
4. Wait for everything to propagate.

What you will get

Your content will be served from a URL of the form http://nicholasjohnson.com.

Visiting http://www.nicholasjohnson.com will return a 301 redirect to the naked domain.

The path will be respected by the redirect, so traffic to http://www.nicholasjohnson.com/angular will be redirected to http://nicholasjohnson.com/angular.

You can have one project page per repository, so if your repos are open you can have as many as you like.

Here's the process:

1. Create A records

For the A records, point @ to the following ip addresses:

@: 185.199.108.153
@: 185.199.109.153
@: 185.199.110.153
@: 185.199.111.153

These are the static Github IP addresses from which your content will be served.

2. Create a CNAME Record

For the CNAME record, point www to yourusername.github.io. Note the trailing full stop. Note also, this is the username, not the project name. You don't need to specify the project name yet. Github will use the CNAME file to determine which project to serve content from.

e.g.

www: forwardadvance.github.io.

The purpose of the CNAME is to redirect all www subdomain traffic to a GitHub page which will 301 redirect to the naked domain.

Here's a screenshot of the configuration I use for my own site http://nicholasjohnson.com:

3. Create a CNAME file

Add a file called CNAME to your project root in the gh-pages branch. This should contain the domain you want to serve. Make sure you commit and push.

e.g.

nicholasjohnson.com

This file tells GitHub to use this repo to handle traffic to this domain.

4. Wait

Now wait 5 minutes, your project page should now be live.

Devitrify

Github's instructions say "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." Isn't that what you're doing with A records and a CNAME in your DNS file? – Dunlop

No, the apex domain has a static IP. The www subdomain has the CNAME. – Devitrify

@superluminary, i repeated your process, and i have two issues, 1) I'm using freeDNS afraid.org for DNS sharing, which does not allow to add trailing . in username.github.io.. 2) when i added github.io url without trailing ., mydomain.com is working, but i cannot acces with www.mydomain.com ?? – Rajab

Hi bistaumanga, I don't have any experience with afraid.org, but I believe the dot is required. Afraid might be adding it for you. – Devitrify

The part that I couldn't figure out via GitHub docs was what URL to use for the project. Thanks for this answer: "this is the username, not the project name." so use yourUserName.github.io. – Reni

is the last dot needed at the end of forwardadvance.github.io.? – Shanklin

Hi @StéphaneBruckert - yes it is, unless your DNS provider inserts it for you. – Devitrify

Make sure you wait at least ~10 minutes for this to propagate. It takes a while. – Depolymerize

@Depolymerize - It depends also on your domain's TTL settings. – Devitrify

@Devitrify can you please elaborate? I (and I'm sure anyone else reading) would appreciate it :) – Depolymerize

Hi @Depolymerize - The global DNS system forms a gigantic web with DNS servers talking and passing data around. The data about any one domain is cached for a period, we call this the Time to Live or TTL. The lower your TTL is the more often the DNS servers will check for updates on your domain. – Devitrify

I have updated this solution and really recommend doing it. You can get it to work in other ways, for example using a CNAME for the @ host, but it will break e-mail, etc. This is the best solution I have found. Thank you. – Saline

Thank you! I was stuck on the correct value for the CNAME record in DNS - just organization.github.io, no matter what project under that organization you're trying to serve up. (i.e., NOT organization.github.io/repo) – Jacobian

This approach doesn't work with HTTPS. yourdomain.com will give an SSL certificate error before you can be redirected to the apex domain – Koffler

@ThomasLevesque Using Cloudflare this solution worked great with HTTPS. I did have to wait ~1 hour for it to work. – Trinitarianism

@NateLevin yes, I ended up using Cloudflare as well. I'm very happy with it! – Koffler

Worked flawlessly for me. I was really frustrated and didn't think it was possible. Additionally, I checked "enforce https" in GitHub pages settings. – Mullen

for the CNAME file at root of the repo, should it be www.example.com or just example.com? Should it match what you put in the custom domain box of the github pages settings and does it depend which redirect you want? – Characterize

Answer 3

Short answer

These detailed explanations are great, but the OP's (and my) confusion could be resolved with one sentence: "Direct DNS to your GitHub username or organization, ignoring the specific project, and add the appropriate CNAME files in your project repositories: GitHub will send the right DNS to the right project based on files in the repository."

Ba

I have no idea what "sending DNS" means. – Bandsman

Redirect DNS queries, so that HTTP requests with particular domain names get the right documents as responses. – Ba

Answer 4

If you are wondering how to get your domain to appear as www.mydomain.com instead of redirecting the www request to mydomain.com, try this:

CNAME file on gh-pages branch will have one line:

www.mydomain.com (instead of mydomain.com)

No matter your preference on redirection (in other words, no matter what is in your CNAME file on the gs-pages branch), with your DNS provider, you should set it up like this:

A      @    192.30.252.154
A      @    192.30.252.153
CNAME  www  username.github.io

Beestings

@zwacky why can't I just point the CNAME at @? why should "www.mydomain.com" and "mydomain.com" resolve to potentially different IPs? – Accomplishment

so im guessing what you type in the CNAME file should match whats in the custom domain box on github settings page? aka either example.com or www.example.com depending which redirect you want? Either way CNAME on DNS settings is the same, its www -> username.github.io – Characterize

Answer 5

As of Aug 29, 2013, Github's documentation claim that:

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

Nyhagen

I'm confused why they added this behavior. I want my .com to point to github pages, not the other way around. – Astrology

I was really confused by this too. As I now understand it, you can still point yoursite.com to github pages, but yourusername.github.io/yoursite won't redirect to yoursite.com. That's fine because yoursite.com will still work, just make sure to update your dns records and wait for that to resolve. help.github.com/articles/… – Semipalatinsk

This should have SEO (Search Engine Optimization) ramifications for the website. Google is said to demote the results ranking of content that is accessible from multiple domains, which is one of several reasons for applying 301 ("permanent") redirects from username.github.io/projectname to www.projectname.com. – Biopsy

Answer 6

I just discovered, after a bit of frustration, that if you're using PairNIC, all you have to do is enable the "Web Forwarding" setting under "Custom DNS" and supply the username.github.io/project address and it will automatically set up both the apex and subdomain records for you. It appears to do exactly what's suggested in the accepted answer. However, it won't let you do the exact same thing by manually adding records. Very strange. Anyway, it took me a while to figure that out, so I thought I'd share to save everyone else the trouble.

Peoria

Answer 7

Things are lot easier nowadays!

1. Update your Apex domain (@) record to point

192.30.252.154

192.30.252.153

2. Edit your Custome domain field in your github repo settings.

3. www and other subdomains can be updated as CNAME to apex domain.

Lateral

Answer 8

The selected answer is the good one, but is long, so you might not read the key point:

I got an error with the SSL when accesign www.example.com but it worked fine if I go to example.com

If it happens the same to you, probably your error is that in the DNS configuration you have set:

CNAME www.example.com --> example.com  (WRONG)

But, what you have to do is:

CNAME www.example.com --> username.github.io  (GOOD)

or

CNAME www.example.com --> organization.github.io  (GOOD)

That was my error

Camembert

Answer 9

I'd like to share my steps which is a bit different to what offered by rynop and superluminary.

• for A Record is exactly the same but
• instead of creating CNAME for www I would prefer to redirect it to my blank domain (non-www)

This configuration is referring to guidance of preferred domain. The domain setting of www to non www or vise versa can be different on each of the domain providers. Since my domain is under GoDaddy, so under the Domain Setting I set it using the Subdomain Forwarding (301).

As the result of pointing the domain to Github repository, it will then give all the URLs for both of master and gh-pages.

As addition to the CNAME file above, you may need to completely bypass Jekyll processing on GitHub Pages by creating a file named .nojekyll in the root of your pages repo.

Matildamatilde

I would recommend not to use godaddy, but just personal opinion – Tatar

You have no CNAME in the master branch. – Softpedal

@Rubel First: I have pointed out by "instead of creating CNAME." Second: The domain is no more exist so I have removed the live sample.. Thanks to have reminded me. – Matildamatilde