You just hosted a website on GitHub pages and now you’re wondering how to add a custom domain to it to give your website that final touch? Here is how.

This article assumes, that your webite is already hosted on GitHub pages

In the first step, you need to add some DNS records in the domain settings of your custom domain’s domain name registrar. In my case, this is GoDaddy, where the settings look like this:

You just add four new records:

Type: A (the same for all records)

Name: @ (the same for all records)

GitHub pages IP addresses:

185.199.108.153

185.199.109.153

185.199.110.153

185.199.111.153

TTL: you can use the default value (the same for all records)

Save these new records and head over to github.com.

Here, you navigate to the repository of your website. Once there, go to Settings -> Pages.

You should see something like this under “GitHub pages”. Now, you only need to add your custom domain in the “Custom domain” field and hit “Save”. GitHub will run checks in the background, to validate your domain for the use with GitHub pages. This might take a moment. Once done, you can check “Enforce HTTPS”, if this is not happening automatically.

Before you can visit your app under the new custom domain, there is one last thing to do. You need to add a CNAME file to your gh-pages branch. For this, simply click Add file -> Create new file and call this new file “CNAME” (this must be uppercase). Inside this file you add one line. Your custom domain.

customdomain.com

This is it. You have now added a custom domain to your website hosted on GitHub pages. It might take a minute for all these changes to take effect. Once you see “Your site is published at …. ” in the GitHub Pages tab, your site is published and you can visit it under the new custom domain.

Note: In some cases the CNAME file gets added automatically when you save the custom domain under “GitHub Pages”. Just make sure to check if this is the case and add it manually if necessary.

When you make changes to your website and deploy it again, you might see that your custom domain and the CNAME file have been deleted. In that case you will need to add both again in order to use the custom domain. To avoid the CNAME file deletion, you could make a pull request before you commit the changes to the remote repository.