Set up Hugo on Github pages with Github actions

Since I did set up this site yesterday, I have a pretty fresh memory on how I did it. I am going to record it here for posterity so I can redo it if I need to.

I followed most of it from this page, but I also had to tweak it a bit.

This tutorial will assume that you are using a mac, since that’s what I’m using. You can check out on how to install Hugo on other systems if you still want to use this tutorial, because the GitHub related things are the same regardless of platform.

I will also assume that your GitHub username is fooname, so I don’t have to type to many letters all the time.

But first, let us look at what Hugo is. In their own words:

Hugo is one of the most popular open-source static site generators.

A static website generator creates a site that doesn’t need any databases, cgi-scripts or other dynamic content. It takes your content, applies templates and creates static HTML files to be served up by a web server or just being loaded straight from a dropbox or a local file.

There are a couple of different ones, there’s a long list here, but I chose Hugo for this site. Tons of premade templates and it seems to have a huge following.

Let’s go!

1. Local set up

For your local development and testing you will need to create a repo for your template pages, a repo for your github pages and set up Hugo locally to be able to setup the website scaffolding, use the local server and generate the static pages.

You can create two repos on GitHub by logging in and press the plus in the top right corner.

For the template pages, create an empty private repo and call it what you want, like mysite. Don’t add any README.md, just keep it as is.

For the github pages, create another private repo and call it fooname.github.io, otherwise it won’t be served up to https://fooname.github.io when the site is ready.

Start with installing Hugo with the instructions from https://gohugo.io/getting-started/quick-start/.

One thing to note here is to make sure to put the right baseURL in the config.toml in Step 6, otherwise the css files won’t be available and the website, when deployed will look very strange. So change it to something like:

baseURL = "https://fooname.github.io/"

You don’t have to generate the static files yourself in the final step Step 7 and commit them to the mysite repo, since we will use Github actions to do the generation of the static files.

After this you will have to make sure that you add, commit and push the repo by doing this in the site directory:

git add .
git commit -m'First commit of Hugo site'
git remote add origin git@github.com:fooname/mysite.git
git push -u origin master

2. Remote set up

Now it’s time to create a GitHub token to be able to push the finished code to the GitHub page.

First go to your Settings page in GitHub, then to Developer settings and select Personal access tokens and generate a new token with the repo scope added. Make sure you copy the token, since we are going to use it in the GitHub action on the mysite repo.

Go into your mysite GitHub repo on the GitHub web site, go to Settings and find the Secrets menu item. Add a new secret named TOKEN and paste in the secret. This will now allow the GitHub action to push to the fooname.github.io repo.

Now it’s time to add the GitHub action in the mysite repo. Create the file .github/workflows/main.yml and paste the following:

name: CI
on: push
jobs:
  deploy:
    runs-on: ubuntu-18.04
    steps:
      - name: Git checkout
        uses: actions/checkout@v2
        with:
          submodules: true
          fetch-depth: 0

      - name: Setup hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 'latest'
          extended: true
          
      - name: Build
        # remove --minify tag if you do not need it
        # docs: https://gohugo.io/hugo-pipes/minification/
        run: hugo --minify
        
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          personal_token: ${{ secrets.TOKEN }}
          external_repository: fooname/fooname.github.io
          publish_dir: ./public
          user_name: fooname
          user_email: fooname@gmail.com
          publish_branch: master

Now you can push the updated mysite repo. After this, do a change in the mysite repo (maybe create a new post or change some other text) and you should be able to see the Action being executed in the Actions tab on the GitHub website.

3. Use your own domain

For this you will have to create a file in the mysite repo in the static directory called CNAME with the name of your domain that you want to to use in it, for example like this:

www.shinynewthings.net

Since it’s in the static directory, it will be moved as is to the github pages repo when generating the site.

Then you have to update your DNS record at your registrar to have some A records to point to:

185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

4. Use https

To be able to use https on the page, go into the Settings on foobar.github.io repo and enable Enforce HTTPS. Make sure the baseurl is with the https:// prefix, otherwise some css or other files might be inaccessible.

Good luck!