Using a custom domain with GitHub Pages

This blog is part of a series where I document rebuilding a website that relies on HTML, CSS and Bootstrap in React.js using the Next.js framework to improve performance, reduce costs and increase my workflow for future changes.

The finished website (hosted on GitHub Pages): https://wallisconsultancy.co.uk
The source code: https://github.com/james-wallis/wallisconsultancy

Using a custom domain with GitHub Pages

Configuring a custom domain for your GitHub Pages site - GitHub Docs

In my previous blog I demonstrated how to run a static website on GitHub Pages. But it was using a default domain name specific to GitHub as wasn't very professional. We can fix this by making it accessible using our own domain name of choosing (wallisconsultancy.co.uk in my case).

Let's modify GitHub Pages to use a custom domain. This will be done in three steps:

1. Modify .travis.yml
2. Add custom domain to GitHub Pages
3. Update DNS settings

Modify .travis.yml

First we need to modify the .travis.yml file we created in the previous to add a fqdn field.

The fqdn field tells Travis to create a CNAME file with our domain in each time we push to the gh-pages branch. If we don't keep creating this, it will be deleted on the next push.

language: node_js
node_js:
  - 12
cache:
  directories:
  - node_modules
script:
  - npm run eslint
  - npm run build
  - npm run export
  - touch out/.nojekyll
deploy:
  provider: pages
  skip_cleanup: true
  github_token: $github_token
  local_dir: out
  fqdn: wallisconsultancy.co.uk # This instructs Travis to create a CNAME file with wallisconsultancy.co.uk as the contents on every deployment to the gh-pages branch
  on:
    branch: master

Add custom domain to GitHub Pages

Next we need to tell GitHub that we are going to use a custom domain.

To do this:

1. Go to the settings of your GitHub repository for the project
2. Scroll to the GitHub Pages section
3. Enter your domain in the Custom Domain section

GitHub Pages settings with a custom domain

Your .github.io/repository domain will now redirect to your custom domain.

However, the website will not yet be reachable as we need to update the DNS settings for the domain name.

 Update DNS settings to point to GitHub Pages

Now GitHub Pages is expecting to be reached via a custom domain and will redirect the old user.github.io/ to it. We now need to set the domain up so that it points to the GitHub server where the website is being hosted.

To update the DNS settings you need to go to your DNS provider and do the following:
Note: I am using Digital Ocean so all the examples are using their UI

Create a CNAME for www.yoursite.com that points to your .github.io address without the subpath.

Example:

My CNAME record settings on Digital Ocean

Optional, using an apex domain rather than www.

If you want your domain to be yoursite.com rather than www.yoursite.com you need to do a further step.

Create an A record to point to the following IP addresses (check the GitHub docs to verify they haven't changed since the writing of this post.

Example:

My A record settings on Digital Ocean

That's it
You've successfully setup your website to run on GitHub pages using a custom domain name. It might take a few minutes for the DNS changes to update but soon your website will be production ready!

Note: If you modified your code for the GitHub subPath issue above, you can now tear this code out.

Roundup

This blog demonstrated how to setup a Next.js website onto GitHub Pages with a custom domain name.

The Wallis Consultancy website is now published into production. This marks the end of the series of blog posts in which I rebuilt the old Wallis Consultancy website that ran using Bootstrap in React.js using Next.js and finally hosted it on GitHub Pages.