I’ve been working on a project for over a month now. It’s currently a static page with a single(bundled) JavaScript file hosted on GitHub Pages.
I purchased a domain from Domain King so I could attach it to my site, instead of using the ORGANISATION/USER.github.io domain provided by GitHub. However, there was a problem.
With the domain attached, my site was no longer accessible over HTTPS, so I needed to add SSL. GitHub provides great documentation on this, and the setup is usually straightforward — update DNS records, and wait a few minutes.
Unfortunately, Domain King requires an additional payment for DNS management, so I needed an alternative solution. Enter Cloudflare.
Step 1 - Add Your Domain To Cloudflare
- Create a Cloudflare Account: Sign up at Cloudflare and add your domain.
Get Cloudflare Nameservers: Cloudflare will provide two nameservers specific to your domain.
Update Domain King Nameservers: Log in to your Domain King account and replace the default nameservers with those provided by Cloudflare.
Note: Nameserver changes can take up to 24 hours to propagate, but they often complete sooner. Once this step is done, Cloudflare will manage your domain’s DNS records.
Step 2 - Add DNS Records For GitHub Pages
With Cloudflare managing your DNS, you’ll now add records to point your domain to GitHub Pages. These records tell the internet where your website is hosted. See this page for more information.
Proxy Status
In Cloudflare’s DNS management interface, you’ll see a switch for “Proxy status.” This setting determines whether Cloudflare acts as an intermediary (proxy) between your visitors and the origin server.
For GitHub Pages, proxying must be disabled because GitHub needs direct access to your DNS records to validate your configuration and issue an SSL certificate.
Ensure all relevant DNS records are set to DNS only to prevent issues with SSL generation.
Set all records to DNS only (unproxied) so that GitHub can validate your configuration and generate an SSL certificate.
A Records
Add the following A records with the record name set to @ (root domain):
- 185.199.108.153
- 185.199.109.153
- 185.199.110.153
- 185.199.111.153
AAAA Records
If you want to support IPv6, add the following AAAA records with the record name set to @:
- 2606:50c0:8000::153
- 2606:50c0:8001::153
- 2606:50c0:8002::153
- 2606:50c0:8003::153
These DNS records tell the Internet that your domain points to GitHub pages.
Subdomain or not?
If you own a domain like example.com, you can choose to link either the main (apex) domain example.com or a subdomain such as blog.example.com to your GitHub Pages site. The process involves adding the relevant CNAME records:
- Apex Domain: Add a CNAME named
wwwwith a target ofUSERNAME.github.ioorORGANIZATION.github.io, depending on whether the repository belongs to a user or an organization. - Subdomain: Add a CNAME named after the subdomain (e.g.,
blog) with a target ofUSERNAME.github.ioorORGANIZATION.github.io. For instance, to create a subdomain forblog.example.com, create a CNAME namedblogpointing to the appropriate GitHub Pages target.
Step 3 - Configure GitHub Pages
- Add Custom Domain: Go to the “Pages” section in your repository’s settings and enter your custom domain.
- Save and Wait: GitHub will automatically generate an SSL certificate. This process may take a few minutes to several hours.
- Enforce HTTPS: Once the certificate is ready, enable the “Enforce HTTPS” option in the same settings.
Troubleshooting
Check DNS Propagation
Use tools like whatsmydns.net to verify that your DNS changes have propagated globally.
Test Your Website
Access your site over both HTTP and HTTPS to ensure it’s accessible and secure.
Common Issues
- Improper DNS Configuration: Double-check that all required records are present and set to “DNS only.”
- SSL Certificate Delays: Be patient; GitHub’s SSL generation can take time.
Alternatives
If you prefer, you can use Cloudflare to manage SSL instead of GitHub. Here’s how:
- Set all DNS records to proxied in Cloudflare.
- In Cloudflare’s “SSL/TLS” settings, choose the “Full” SSL option.
Conclusion
By following these steps, you can host your website on GitHub Pages with a custom domain. Whether you use GitHub’s SSL or opt for Cloudflare, this setup ensures your site is both accessible and secure.
You should also consider switching to Spaceship over Domain King, like I have.