Using GitHub Pages with Hugo and TravisCI

What and Motivation

I recently setup a GitHub Pages page (see here) as a personal info/who am I type of page as I was curious how GH Pages works and also because I wanted to get familiar with TravisCI.

tldr;

Source code is here. GH Pages only allows you to host off of “master” branch and TravisCI deletes history on deploy, meaning you have to have a “long running” branch which is annoying. Hugo is very easy to use and setup (probably due to being written in Go lang).

Pre-requisites

Need a GitHub account and a TravisCI account (both are free, TravisCI won’t charge unless you go “over” a certain number of builds or something)

Need to be able to run Hugo locally

Setup

Create a repository in GitHub with the name [YOURUSERNAME].github.io (e.g. srkinz84.github.io). By using this naming convention it automatically flags the repository as a GitHub Pages repo.

Then go to the “Settings” for the repo and ensure that Pages is enabled:

Then, if you want to you can commit a “index.html” to master and see it show up when you hit the URL (just to verify it’s working).

Create a simple Hugo page

So, if you go through the Hugo Quick Start you should get a fairly good idea how to use it to generate web pages/blog posts etc… If you’re just after a simple website, with similar content to mine, have a look at the index template in my source. If you’re after something more complicated you can have a look at the Hugo documentation page.

Create a “dev” branch (can name it whatever you like)

So, in order to get around the limitation that you have to publish to the “master” branch and that when you publish it’ll nuke the “history” of that branch, we need to create a separate “long lived” branch. I’ve called mine “dev” but really, you can call it whatever you like.

This is the branch that we’ll be deploying from and that TravisCI will be “listening on” for any changes to build and deploy.

I’d imagine that the workflow would be that when adding a feature/bugfix/content you’d branch off of the “dev” branch, do the work until it’s “ready” and then create a PR to merge the changes back into the “dev” branch.

Generate a GitHub OAuth token

As per the TravisCI Pages Deploy documentation, we have to generate a “Personal Access Token” in GitHub (it’s an OAuth token associated with your account) before TravisCI will be authorized to “commit” (also “deploy” in this context) to the repository. The instructions for generating a Personal Access Token can be found here.

Create TravisCI file

The description of how to configure the GitHub Pages deploy from TravisCI is taken from the documentation, which can be referred to for more details. The contents of the .travisci.yml file (which is used to create and configure the build in TravisCI) are as follows:

install:
  - wget -O hugo.tar.gz https://github.com/gohugoio/hugo/releases/download/v0.36/hugo_0.36_Linux-64bit.tar.gz
  - tar xvfz hugo.tar.gz
  - rm -rf public

# Build the website
script:
  - ./hugo version
  - ./hugo

# Deploy to GitHub Pages
deploy:
  provider: pages
  skip_cleanup: true
  local_dir: public
  github_token: $SERGE_GH_TOKEN
  target_branch: master
  on:
    branch: dev

The first “install” section deals with downloading the Hugo binary and extracting it.

The “script” section prints out the version of Hugo that we’re using and executing it to generate the HTML/CSS/JS/XML.

Finally, the “deploy” section using the “pages” deploy provider to deploy our “public” directory to the “master” branch (and the “on branch” bit just tells TravisCI to only deploy off of the “dev” branch).

Commit, push and watch it build and deploy

Finally, after you’ve modified your content and tested it locally to ensure that it looks the way you want it to, commit your source (exclude the “public” directory) and push it to the “dev” branch.

Shortly after, you should see the build starting in the TravisCI interface:

Hopefully the build logs show that the build was successful and it “goes green”:

At this point, we should have a website that’s publicly viewable, in version control as well as having a build/deploy pipeline in place to automate the boring bits.

Further stuff to add in future

So, while this works, there are some things that would be nice to add, off the top of my head:

  • A “health check” to verify the site is “up” and is showing the correct version of our website
  • Verify there’s no broken links on the website
  • A check to ensure that our website conforms to accessibility standards
  • A check to ensure that our website conforms to search engine optimization standards

Basically a “test” suite to ensure that not only did we build and deploy, but also that we tested that the website still met our requirements.

 

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.