LearnUsing GitHub Pages To Host Your Website

Matt West
writes on August 16, 2013

So you want to launch a simple website but don’t want to have to go through the dull process of setting up yet another hosting package. There is an easier solution. If you just want to launch a simple static website you can use GitHub Pages to host your site for free.

Let’s get started.

Note: This post assumes that you have a GitHub account and some basic knowledge of the version control system Git.

Create Your GitHub Repository

The files that make up your website will need to be stored within a GitHub repository. If you’re creating a website to promote one of your existing GitHub projects you can add the website files to a new branch, otherwise you can just setup a new repo for your site.

Note: If you are not adding your website files to an existing repo make sure that you setup a new repo before continuing.

Now open up terminal (command prompt on Windows) and make sure that you have a copy of your GitHub repo on your computer. Once you got your local copy, move into the project folder using the cd command.

// Retrieve a copy of your GitHub repo.  
git clone https://github.com/user/repository.git
// Move into that directory.
cd repository

Note: Make sure that you change the clone URL to the URL of your GitHub repo. This can be found on the main project page.

Creating an Orphan Branch

Now you need to create a new orphan branch within your repo that will hold all of your website files.

This new branch should be called gh-pages.

git checkout --orphan gh-pages

If you already had files in the master branch of your GitHub repo you now need to delete these from the new gh-pages branch. To do this you can use the following command:

git rm -rf .

Adding Your Website Files

Now that your repo has been properly setup it’s time to add all of the HTML, CSS and JavaScript files that make up your website. Once you have added these to your repo you need to commit the changes. To do this you can use the following command.

git commit -a -m "Adding pages"

Note: The -a flag is shorthand for git add .

Pushing Your Changes to GitHub

Okay so you’ve got all your files where they need to be. The only thing left to do now is to push the new gh-pages branch up to GitHub. You do this using the git push command.

git push origin gh-pages

That’s it! Your website should now be available at http://username.github.io/repository/.

Using a Custom Domain

The last thing I want to cover in this post is how you can use your own domain name with your new GitHub-hosted website.

First you will need to create a new file in your GitHub repo called CNAME that contains the domain name (or subdomain) that you wish to use. This file should be placed in the gh-pages branch if you are using project-pages (as we have been in this post). If you are using user-pages the file should be placed in the master branch.

Your CNAME file might look like the following:

teamtreehouse.com

Next you will need to update the DNS records for your domain name. This is usually done through a control panel provided by your domain registrar.

If you want to use a root domain (such as teamtreehouse.com) for your website you will need to setup a new A record that points to the IP address:

192.30.252.153 or 192.30.252.154

If you are using a subdomain (such as blog.teamtreehouse.com) it’s best to create a new CNAME record that points to your GitHub user subdomain (**username**.github.io). This is so that the DNS will be automatically adjusted if the servers IP address changes on GitHub.

Note: For information about the difference between CNAME and A records check out this video.

It may take a little while for your DNS changes to take effect. This is usually no more than a few hours. Once the changes have gone through, you should be able to access your new website from your custom domain name.

Final Thoughts

In this post I’ve showed you how to host pages that you’ve created yourself but it’s worth noting that GitHub also has a tool for automatically generating pages for your projects. You can launch this tool from the project settings page.

GitHub pages does limit you to using static assets (HTML, CSS and JS) for your websites, but you could use something like Jekyll to make it easier to generate these files.

It’s not going to meet everyone’s needs but if you just want to launch a simple website, GitHub pages is a quick and easy way to get started.

38 Responses to “Using GitHub Pages To Host Your Website”

  1. daftar situs judi bola terpercaya on April 12, 2018 at 8:16 am said:

    It’s difficult to find well-informed people about
    this topic, however, you sound like you know
    what you’re talking about! Thanks

  2. fabrizio on February 22, 2018 at 9:27 am said:

    Hi,
    thanks for the nice article. I have my website hosted on github and I use cloudflare for the custom domain DNS. Could you please advise for the best way to get a mail server working?

    Cheers
    Fabrizio

  3. Jual Handle Pintu Di Pandegelang on February 1, 2018 at 10:34 am said:

    It’s not my first time to pay a visit this site, i am
    browsing this web page dailly and take nice facts from here everyday.

  4. Kasia on August 27, 2017 at 10:12 am said:

    I’m don’t know much of GitHub yet but for what I know, anyone can access and edit the files in a repository, isn’t that right? So doesn’t that mean anyone could edit the pages I publish?

  5. Abhay B on July 23, 2017 at 9:44 pm said:

    This really helped me. Thanks a ton.

  6. Keith on June 13, 2017 at 7:15 pm said:

    Hey guys, I know this is an old thread but hopefully someone is still active and may help, may seem like a dumb question but when it comes to adding the files into the gh-pages branch what do i put where it says “adding Pages” ?

    For instance say i want to add multiple files in a folder on my desktop what would be required?

  7. DEBANJAN on January 29, 2017 at 10:50 am said:

    Hi

    Nice article. I ausually use Desktp app for Gethub repository. I have published a webpage too. I am a student. And now I have a big challenge…..

    How I can edit my existing page design?
    how can I add some links to my existing pages?
    How I can add new pages?
    How I can add any downloadable content on my page?

    I previously created a project. Now I want to update the swf, want to add a downloadable pdf, Want few changes in the design also. Even Now we are working on a new project, so the new project page should be published under the mail page.

    Pls Pls Pls Help.

  8. Sachin S Rawat on September 11, 2016 at 10:37 pm said:

    Thanks for this info. I did exactly this for my custom domain (pointing to my user page) and it shows an error saying – Domain’s DNS record could not be retrieved. How do I solve this?

  9. Arkya on July 15, 2016 at 12:52 pm said:

    Hey, my personal blog is hosted on github. How do I check if anyone is actually visiting my blog?

  10. reseller hosting account on June 5, 2016 at 12:00 am said:

    So make your web presence stand out, no matter what your experience level. This article can concentrate on dedicated servers and to completely perceive what it will and the way it fluctuates from alternative types of hosting, it’s best to investigate the opposite forms that it shares the market with. This is suitable for web owners who are new to online marketing since they will only have to pay for the services they need and they can just upgrade their plans later on if necessary.

  11. park on March 23, 2016 at 3:36 pm said:

    Thanks for your article, my question can I use it for a WordPress website or a rails website by uploading the files.
    Thanks

    • Webs by Todd on April 25, 2016 at 8:24 am said:

      WordPress and rails are not static in nature. When a person visits a WordPress or rails site, the server has to do some work in order to generate the HTML, CSS, and JavaScript files. You will have to use a static site generator or simply write HTML, CSS, and JavaScript from scratch in order to take advantage of GitHub Pages.

  12. David Farrell on February 11, 2016 at 11:30 am said:

    Nice article – btw in “git commit -a” the “a” stands for all, not add. It only commits content that has already been added.

  13. Vitaly on January 21, 2016 at 1:33 am said:

    Literally shitting myself, that after so much time using GitHub I found out about all this only now.

    Thank you so much for this article!!!!

  14. Rowe Morehouse on December 30, 2015 at 2:39 am said:

    This article has incorrect information concerning configuring the IP address for the A record at your DNS provider.

    Two A records should be added, with the following IPs:

    192.30.252.153
    192.30.252.154

    See this article:
    https://help.github.com/articles/tips-for-configuring-an-a-record-with-your-dns-provider/

  15. VADER on December 9, 2015 at 12:22 am said:

    I HATE YOU LUKE SKYWALKER! I HATE YOU!

  16. Ramil on November 30, 2015 at 8:54 pm said:

    Any thoughts on the file size limit you can host for your static website? Thanks 😀

  17. Caspar on October 28, 2015 at 7:52 am said:

    The IP given in this article has been deprecated! See here: https://github.com/blog/1917-github-pages-legacy-ip-deprecation

  18. Pravin Purohit on September 25, 2013 at 9:32 am said:

    Well Cool Article . But matt do you know any alternatives to github for hosting projects?

  19. Gersande on September 21, 2013 at 1:59 am said:

    Excellent article !

  20. Vladimir Varankin on August 30, 2013 at 2:30 pm said:

    Nice article! But what are the reasons to store gh-pages branch as an orphan?

  21. michaelbraganza4 on August 23, 2013 at 8:25 am said:

    Hello Friends,

    This is really good blog. Thanks for sharing this information.

    Site:- http://www.myit.ie

    Keywords:- Website Design Dublin, Web Design Dublin, Web Design Ireland

    Thanks 🙂

  22. Webmaster Blog on August 19, 2013 at 5:43 am said:

    Just wish to say your article is as amazing. The clearness in your post is just cool and i could assume you are an expert on this subject. Fine with your permission let me to grab your feed to keep updated with forthcoming post. Thanks a million and please carry on the gratifying work.

  23. tanluc on August 19, 2013 at 5:04 am said:

    Thanks so much Matt West because this shared.

    tai game mien phi

  24. Walt on August 18, 2013 at 4:26 pm said:

    Mr. West: You da bomb!

  25. Tom Ireland on August 18, 2013 at 10:51 am said:

    Awesome tip, bud. Just recently created my own site on there. Pretty awesome stuff and Jekyll is cool.

  26. Jonathan Sky on August 17, 2013 at 4:40 pm said:

    thanks for share this

    Agen Bola

    Agen Judi

    Prediksi Skor Bola

  27. Matt Smith on August 17, 2013 at 11:04 am said:

    Cache headers are set to expire after 10 minutes in GitHub, correct? Can that that be changed?

  28. VonVictor Valentino Rosenchild on August 16, 2013 at 8:07 pm said:

    Thank you for sharing this information. Although I have been using GitHub for a while now, I never thought about using GitHub pages to host a website.

    Thanks for the info!

    Kindest regards,

    VonVictor V. Rosenchild

  29. Alexander Goncharov on August 16, 2013 at 9:48 am said:

    lifehack 😀

Leave a Reply

You must be logged in to post a comment.

Want to learn more about HTML?

HTML is what the Internet is built on. Learn how to build your first website from scratch.

Learn more