508

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 this 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?

phwd
  • 19,975
  • 5
  • 50
  • 78
rynop
  • 50,086
  • 26
  • 101
  • 112
  • 10
    I've set up http://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. – James M Jan 31 '12 at 15:56
  • In my case, just placing the CNAME file in gh-pages branch did the trick, thank you! – jarandaf Apr 26 '16 at 14:47

9 Answers9

635

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.

  1. 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:

enter image description here

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.

starball
  • 20,030
  • 7
  • 43
  • 238
rynop
  • 50,086
  • 26
  • 101
  • 112
  • 14
    As of Apr 19, 2012, [GitHub's documentation](http://help.github.com/pages/) uses `204.232.175.78` as the IP address. – Aseem Kishore Apr 20 '12 at 02:24
  • I am getting invalid hostname for 204.232.175.78 – fccoelho May 01 '13 at 22:10
  • I think it's also okay to set up a CNAME that points www to the root. – Mark May 06 '13 at 20:28
  • Is it possible to set this up with a CNAME (no A record)? – iwein May 15 '13 at 06:28
  • @iwein 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) – rynop May 17 '13 at 14:49
  • 31
    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. – Danny Feb 06 '14 at 23:08
  • 2
    "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." https://help.github.com/articles/my-custom-domain-isn-t-working - 3/8/14 – eddywashere Mar 09 '14 at 06:15
  • 11
    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. – superluminary Mar 12 '14 at 22:19
  • @superluminary 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. – rynop Mar 13 '14 at 15:11
  • @rynop I can convert as of today, this method still works perfectly. Thank you so much. – Chris Hough Jul 20 '14 at 18:13
  • 2
    @rynop GoDaddy doesn't allow @ and www to yourusername.github.io, only one CNAME record per subdomain :( – Tejas Manohar Jul 31 '14 at 05:20
  • 2
    For Namecheap domain users, to set up only an apex domain name, [do this in your `All Host Records`.](https://i.imgur.com/hp3S6Hn.png) – tom_mai78101 Nov 20 '14 at 23:39
  • 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 ? – Rahul Sinha Mar 15 '17 at 06:57
  • Pass by Hamburg, and I'll buy you a beer. – creimers Mar 24 '17 at 14:25
  • 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. – elporfirio Aug 07 '17 at 20:37
  • The IPs that you must use can be checked from here: https://help.github.com/articles/troubleshooting-custom-domains/#dns-configuration-errors – lakshayg Dec 17 '17 at 14:12
  • 1
    I've updated the answer to address and include info many of these comments bring up. Thanks for all the feedback! – rynop Jan 31 '19 at 19:54
  • 1
    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? – Foobar Feb 12 '19 at 23:22
  • 1
    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? – j b Dec 04 '19 at 10:12
  • 1
    "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... – Grodriguez Mar 26 '20 at 19:15
  • 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://stackoverflow.com/a/58672792/450398 – Grodriguez Mar 26 '20 at 19:28
  • "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? – Marian Paździoch Apr 15 '20 at 06:48
  • This comment https://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. – dash2 Dec 16 '20 at 15:03
  • 1
    What if we already have a blog on github_username.github.io? which is my case – Nebula Jul 12 '21 at 17:51
  • 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: https://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. – Peter Aug 03 '22 at 16:06
  • Complete answer and well updated as of March 2023. – Ronen Rabinovici Mar 04 '23 at 21:57
  • 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. – haccks Apr 12 '23 at 08:55
  • 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. – Nex Jun 18 '23 at 10:59
256

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:

A and CNAME records required for Github Static Pages

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.

cremaster
  • 50
  • 7
superluminary
  • 47,086
  • 25
  • 151
  • 148
  • 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? – rda3000 Mar 27 '14 at 17:22
  • 1
    No, the apex domain has a static IP. The www subdomain has the CNAME. – superluminary Mar 27 '14 at 21:23
  • 4
    @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 ?? – bistaumanga Apr 22 '14 at 10:04
  • 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. – superluminary Apr 22 '14 at 10:30
  • 4
    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.` – pkamb Oct 01 '15 at 20:30
  • is the last dot needed at the end of `forwardadvance.github.io.`? – Stéphane Bruckert Oct 13 '15 at 15:53
  • Hi @StéphaneBruckert - yes it is, unless your DNS provider inserts it for you. – superluminary Oct 13 '15 at 18:27
  • Make sure you wait at least ~10 minutes for this to propagate. It takes a while. – YasharBahman Oct 23 '15 at 06:11
  • @YasharBahman - It depends also on your domain's TTL settings. – superluminary Oct 23 '15 at 08:05
  • @superluminary can you please elaborate? I (and I'm sure anyone else reading) would appreciate it :) – YasharBahman Oct 26 '15 at 06:23
  • Hi @YasharBahman - 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. – superluminary Oct 29 '15 at 23:18
  • 1
    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. – Steven L. Dec 11 '15 at 15:36
  • 1
    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) – Libby Apr 14 '16 at 19:53
  • 1
    This approach doesn't work with HTTPS. https://www.yourdomain.com/ will give an SSL certificate error before you can be redirected to the apex domain – Thomas Levesque May 03 '20 at 21:14
  • @ThomasLevesque Using Cloudflare this solution worked great with HTTPS. I did have to wait ~1 hour for it to work. – Nate Levin Jan 02 '21 at 18:32
  • @NateLevin yes, I ended up using Cloudflare as well. I'm very happy with it! – Thomas Levesque Jan 03 '21 at 21:31
  • Worked flawlessly for me. I was really frustrated and didn't think it was possible. Additionally, I checked "enforce https" in GitHub pages settings. – Sahil Singh May 22 '21 at 06:00
27

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."

blacktide
  • 10,654
  • 8
  • 33
  • 53
Jim Pivarski
  • 5,568
  • 2
  • 35
  • 47
21

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
Simon Wicki
  • 4,029
  • 4
  • 22
  • 25
Phil
  • 2,732
  • 19
  • 20
  • @zwacky why can't I just point the CNAME at @? why should "www.mydomain.com" and "mydomain.com" resolve to potentially different IPs? – aaa90210 Jun 28 '17 at 05:53
15

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.

Amio
  • 185
  • 1
  • 5
  • 3
    I'm confused why they added this behavior. I want my .com to point to github pages, not the other way around. – Jordan Scales Oct 04 '13 at 16:35
  • 9
    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. https://help.github.com/articles/setting-up-a-custom-domain-with-pages#apex-domains – eddywashere Mar 09 '14 at 06:21
  • 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`. – BorromeanNot Nov 28 '16 at 16:47
3

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.

Brandon Fosdick
  • 15,673
  • 4
  • 21
  • 20
3

Things are lot easier nowadays!

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

192.30.252.154

192.30.252.153

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

enter image description here

  1. www and other subdomains can be updated as CNAME to apex domain.
Rafaf Tahsin
  • 7,652
  • 4
  • 28
  • 45
3

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

Rafa Nogales
  • 614
  • 8
  • 13
0

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.

eQ19
  • 9,880
  • 3
  • 65
  • 77