Websites are getting easier to host everyday, with many services offering packages starting at less than $5 a month. But, if you just want a simple site that isn’t going to see a ton of traffic, you may be able to host on Github for free, even with your own domain.
What Is Github Pages?
Github is a code hosting service that provides version control through
git. While it’s commonly used by programmers, a common use case for them is running simple wikis, resumes, or documentation sites that don’t see tons of daily traffic, and just need a place to put up a website for free.
For this, Github Pages was created, and it allows you to host HTML files and other assets free of charge. This isn’t much different from Github’s normal file hosting—you can host files in your repositories entirely for free, and hosting a static site is just like hosting files.
You can have pages for your username, or pages for each repository. By default, Github will assign you a subdomain url like
username.github.io/repository. This can be changed to any custom URL.
What Are Static Websites?
The important thing to note is that Github Pages is only for static websites. This doesn’t necessarily mean your website can’t be interactive, it just means that your website is hosted directly from the HTML, JS, and CSS files.
The main restriction with static websites is that it can’t rely on a server to be changing the content for each request, like with a language like PHP. For example, if you want to have users sign in and view a profile, or host WordPress (which connects to a database server), you’ll have to host somewhere else.
bundle.js file with all the code.
Github Pages Restrictions – Noncommercial Use
Of course, this comes with a few restrictions. Essentially, you’re not supposed to use Github Pages for primarily commercial use. Specifically, they say it’s prohibited from being used as a “free web hosting service to run your online business, e-commerce site, or any other website that is primarily directed at either facilitating commercial transactions.”.
So, if you planned on operating your business off Github Pages, you’ll likely want to look at other alternatives. Two very similar “free hosting” methods are using AWS Simple Storage Service buckets to host static websites, or using Google’s Firebase static hosting. Both work well for both amature and professional static site deployments, and have free tiers that can save you from paying the $10 a month to host your own server.
Github Pages also has size limits and soft bandwidth limits, though they’re fairly reasonable. Your site can’t be more than 1 GB (you are likely going to have a problem serving a site this size anyway) and if you go over 100GB of bandwidth per month, Github may not serve your site. For reference, that amount of data would cost you about $10 a month on AWS.
Setting Up a Page
Github Pages is pretty simple to set up, and if you’re familiar with Github, it should be even easier.
Basically, you have two options for repositories—user pages, or project pages. If you’re using a custom domain, it shouldn’t matter much, but if you want a nice URL, you’ll want to use a user page, which will give you a URL in the format of
username.github.io. If you use a project page, you can have many pages set up, but each will be at
In either case, you’ll have to create a new repository. If you’re making a user page, set this to your username plus
.github.io. Make sure it’s public as well.
After this, you’ll need a Git client to connect to Github and push your website. You can use a terminal, or a GUI client like Github Desktop. Use the URL given to you from the quick setup:
Or, if you’re using the Github Desktop app, you can simply search for it by name:
Then, you’ll need to add your content. If you have an existing template you’d like to use, copy all the assets (HTML, CSS, JS files, images) over to this directory, which is essentially the “webroot” where everything will be hosted from. The most important thing is
index.html, which is the main page of your site.
Once everything works locally, you’ll need to commit the changes, and publish them to Github.
You’ll soon see the new files in your repository, but you’ll have to enable Github Pages for it to fully work. From the repository page, click “Settings” and scroll down to “Pages.” Select the
main branch to serve your website from, and click “Save.”
It may take a few minutes for everything to update, and it will only update 10 times per hour, so don’t make changes too quickly.
You’ll also want to enable “Enforce HTTPS” in the Github pages settings.
Adding a Custom Domain
Once registered, you’ll need to point your domain to your Github page. However, you can’t just paste the URL in here; you’ll need to create a CNAME record that points to
username.github.io. If you plan to use
www, set the Host value to
www. If you want to use the base domain by itself, set the Host value to
After waiting a few minutes for DNS records to sync across the internet, you should be able to see your newly created Github Pages site at your custom URL, and the settings menu should show it as connected.