Using custom subdomain with GitHub repositories
GitHub actually allows you to host websites for your projects directly from the repository itself. It will have URL something like https://<username>.github.io
, you can add your custom domain to it too. If you haven’t done it, GitHub has pretty good documentation about it. You can read it here.
Now, let's suppose you have already set up a custom domain and your default site is accessible through https://example.com
. Now, if you create a new repository named project
, and enable GitHub pages, it will be accessible through https://example.com/project
but sometimes it makes more sense to have a custom sub-domain, like https://project.example.com
. To do this, there are some additional configurations required. Just follow the steps below.
To make the steps more clear, I will use my own, recent project example for which I set up the custom subdomain. My GitHub username is DefCon-007
and my personal website which was available through GitHub pages at https://DefCon-007.github.io
is served from my custom domain with https://defcon007.com
and https://www.defcon007.com
. I now had a new repository named utilobot-website
which contained some HTML and was served at https://defcon007.com/utilobot-website
and I wanted it to be served at https://utilobot.defcon007.com
Step 1: Configure DNS settings
Go to your domain provider’s website and add a new CNAME record with a name as your subdomain and value as your GitHub root URL with a trailing dot(No it is not a typo). In my case the name was utilobot
and the value was defcon-007.github.io.
Step 2: Add CNAME file
Now, add a new file named CNAME
to your repository with just a single line in it, that is your complete URL.
You can also go to the repository settings and enter your custom domain in the GitHub Pages section, it will automatically add the CNAME file.
That’s it, you have a custom domain for your GitHub project now. Try opening it with http
first, and it is working fine, you can select Enforce HTTPS option
in the repository settings page.
Troubleshooting
- If the custom sub-domain does not work, try after some time, so that the DNS records are propagated, also try removing the trailing period from the URL in step one, it works sometimes.
- If you find that the Enforce HTTPS checkbox is disabled, and your custom domain is working fine with
http
, try deleting the CNAME file, push the changes, create the same CNAME file with the same content and push again. It should be enabled now.
Thanks for reading.
This article was originally published at http://www.defcon007.com/GitHub-Custom-Domain/