Publish Websites on GitHub Pages with a Custom Domain

Last Updated : 27 May, 2024

GitHub Pages is a free hosting service provided by GitHub that allows you to publish static websites directly from your GitHub repositories. By default, GitHub Pages provides a domain in the format - username.github.io/repository, but you can also use a custom domain for your website. This article will guide you through the process of publishing websites on GitHub Pages with a custom domain.

Prerequisites

A GitHub Account
A GitHub Repository
A Custom Domain

Steps to Publish Website on GitHub Pages

Step 1. Setup up a GitHub repository

Set up an empty GitHub repository just the way you normally do. Give any name to the repository. You could keep the repository either public or private, your choice.

Step 2. Push your code on the repository

Push the entire code onto the repository. Ensure that you have the index.html in the root directory or in a folder named docs (you’ll understand why in the next step).

Here's the directory structure:

- index.html
- public
   |_ css

Step 3. Enable GitHub Pages

Head to the Settings tab of the repository and scroll down to where it says GitHub Pages. By default, the options look like this:

For the Source, click the dropdown where it says None and choose the branch where your code is present, in my case it’s main.

As soon as you select the branch, a new dropdown will appear. Choose the respective folder (root/docs) where your code is present. Click Save.

Scroll back down to the GitHub Pages section and you should see something like this:

Head to the URL and you should see your website live on the internet.

Step 4. Set a custom domain

In the next step, we’ll explain how to get a free custom domain.

Now to set up a custom domain, enter the domain name in the Custom domain section, in my case, it’s github-pages.tk

Click Save. This adds a new CNAME file to your repository.

Sometimes the Enforce HTTPS option is auto-enabled, if it’s not, enable it manually to get a free SSL certificate for your website. Sometimes, it could also take time to give you the option to enable it.

Step 5. Get a custom domain

To get free custom domains, I use Freenom. If you already have the domain from another provider, the below steps should be similar.

Select the available domain and complete the checkout process.

Now go to Services > My Domains. Select the Manage Domain option against the domain you just got and head to Manage Freenom DNS.

Now, all we need to do is set A & CNAME records for the selected domain.

For A record, add four entries:

185.199.108.153

185.199.109.153

185.199.110.153

185.199.111.153

To redirect www subdomain to the original domain, add a CNAME record with your GitHub pages profile URL with a .(dot) in the end, in my case, it would be ‘ishaanohri.github.io.’.

Just to be sure, check for the latest IPs in GitHub’s Official Documentation.

Save the records and wait for some time. Your website would be live on www.custom-domain.com and custom-domain.com. Sometimes it may take up to 24 hours to reflect the changes.

Your website is now live on your custom domain. Now, any changes you push onto the selected branch of the repository will be published live on your domain.