I started to dive back into web programming and learned that you can host a small project on Github Pages for free, if you have an account (if you don’t have a Github account, you can get sign up here which is also free). Github’s instructions only outline the process for for setting up your site when you use a template or copy someone else’s repository. In this blog post, I walk through the process how to do this when you don’t want to use an existing repository or template, and want to add a custom domain name. FYI, I have a Windows 10 PC and the tips I share may not apply for Apple devices. I also assume that you’ve created a site that is ready for hosting.
Install & Configure Git
Assuming that you have a Github account and are signed in, you need to download and install Git on your PC. If you haven’t used Git before from the command line or PowerShell, it’s worth taking some time and skimming the book on their site to learn some of the basics, which I will not cover here. Once you’ve installed Git, follow the instructions here to set up your username–you’ll need to decide if you want to use the same name for every repository on your computer or set up a new one each time–then set up your email address using the instructions here. Lastly, you’ll need to authenticate with Github using the instructions here. Github recommends using HTTPS. I would stick with this method because it’s the least complicated.
Sign into Github and select the “+” by your profile icon in the top right-hand side of the screen to create a new repository:
When prompted to name the repository, it should be your username, followed by “github.io”
Setting up Github Pages
Once you’ve created the repository, go into your settings:
Scroll down to Github Pages, where you’ll see the option to change the Source. Select “gh-pages branch.” Also, check the box that says “Enforce HTTPS.” –If you continue to scroll down, you’ll see other various options such as the option for deleting your repository, transferring it, etc. You may be tempted to select the option to make the repository private but know that you cannot do this if you have a standard Github account.
Now, scroll back up to the top of your settings and add the name of your website. For example, I named mine “Portfolio.”
Adding your website files
There are two ways to do this:
(1) You can manually upload the files/folders for your website to your repository, one by one.
(2) You can push your files to your repository using Bash, PowerShell, or CMD. I’ll walk through the steps for using the command line, since you may not want to download and install any additional software.
- Within the command line, change the current working directory to the folder that your project is saved in (which is your local repository). For example:
- Next type:
git add .
This will the files in the folder and stages it for commit. If you made a mistake and want to unstage the files, type:
git reset HEAD YOUR-FILE
- If everything is correct, then you can commit by typing:
git commit -m "first commit"
The -m “first commit” is an optional message that you included with the commit. You can, and should, add a message with each commit so that you can more easily track the changes that you made. To remove the commit or modify the file, you can type:
git reset --soft HEAD~1
- Lastly, push the files to your Github repository by typing the following:
git push origin gh-pages
“gh-pages” is the branch that we just created for hosting your site. You can also push to the “master” branch and then push those files to your “gh-pages” branch, if you prefer.
Now, if you don’t have a custom domain, you’re done! Depending on how large your files were, your website should be live within 5-20 minutes. You can see it by going to
Adding a Custom Domain Name
If you purchased a domain name, you can add your domain name in the Settings under the Github Pages section:
Then log into your domain name provider and create a CNAME record that points to your subdomain on Github. (CNAME record where host is www and the site is your-username.github.io.)
You may also need to redirect site:
Source URL: your-custom-domain-name (e.g., example.com)
If you have an APEX domain, you’ll also need to create a 4 ANAME records, where you’ll provide the following information:
220.127.116.11 18.104.22.168 22.214.171.124 126.96.36.199
It may look something like this (depending on your DNS provider):
Now, you should be done. It may take a while before you can view your site live–some people said a day or two… Mine was live within an hour:
Pretty big change from my previous site:
Github is sensitive to capitalization, so if you have photos that end .JPG rather than .jpg, they will not show up on your site.
Also, the space that you get with a free account is of course limited, so try to keep large files like videos and photos to a minimum.
Lastly, be super super careful not to upload any sensitive or private information, since they will be accessible to anyone who visits your Github profile.