What and Motivation
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).
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
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:
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.