Automating hugo builds using CircleCI

Let someone else run your build server

Published October 29, 2018 #static_sites #hugo #howto

Here's a simple CircleCI configuration to pull down the latest version of your hugo site on GitHub commits, build it, and then push it to github pages.

Let’s set that up, following their documentation on how configure CircleCI to build static sites.

Create .circleci/config.yml

version: 2
        - gh-pages
      - image: cibuilds/hugo:latest
    working_directory: ~/hugo
      HUGO_BUILD_DIR: ~/hugo/public

      # install git
      - run: apk update && apk add git

      # checkout the repository
      - checkout

      # install git submodules for managing third-party dependencies
      - run: git submodule sync && git submodule update --init

      # Link the public dir to the gh-pages branch

      - run: rm -fr $HUGO_BUILD_DIR && git worktree add -B gh-pages $HUGO_BUILD_DIR origin/gh-pages

      # build with Hugo
      - run: HUGO_ENV=production hugo -v -d $HUGO_BUILD_DIR

      # Set some variables to add to the commit message
      - run: git config --global "" && git config --global "CircleCI Bot"

      # Push the generated files back to github
      - run: cd $HUGO_BUILD_DIR && git add --all && git commit -m "Automated publish to gh-pages [ci skip]" && git push

Commit and add this file to your reposity on GitHub. This runs the hugo build image. It installs git, and then checkout the repo from GitHub. We pull down any submodules if you are using that for themes. We then configure the $HUGO_BUILD_DIR to be a worktree of the gh-pages branch – this is where we are going to host the files in GitHub pages. Then it runs the build itself, adds and commits those files in the gh-pages branch back into the repository, and pushes back to GitHub.

For this to work you need to grant CircleCI write access to your repo which is done by setting it up with your user’s key. Lets get CircleCI working now.

  1. Go to CircleCI and create an account.
  2. Select the single linux container plan.
  3. Add your repository from GitHub that you want to build.
  4. Go to project settings, and under Permissions go to Checkout SSH Keys.
  5. Add User Key to grant permission.
  6. Remove the previous deploy key.

Now when you push your commits to GitHub, you’ll be able to watch CircleCI build them and hopefully see your new content go up shortly!

Read next

See also

Adding a CMS to hugo

Static doesn’t mean dead

Just because we have a static site doesn’t mean that we can’t have an admin tool to write and edit posts! Lets go through how we can add the NetlifyCMS to the site and host it wherever we want. In my case I’m storing the code on GitHub and also serving the pages from GitHub Pages. Netlify also seems like a really promising company with a number of other services that they offer, so I’d encourage you to check it out.

Read more

Building a hugo site and theme with Bootstrap

hugo is blazing fast

Now that’s its 2018 its time to retool the blog using hugo. Why not? Hugo is built in golang and is blazing fast and everything is cleaner than it was in the middleman years. One of the reasons that I liked middleman – it’s usage of the rails’ Sprockets library – is no longer a strength. The javascript and front-end world has moved over to WebPack and I’ve personally moved over to create-react-app.

Read more

Slow data and Fast Sites

building fast, searchable, functional sites that fail gracefully

This article walks through the motivations driving and benefits of using a the Seed Architecture for building performant websites using Middleman, React, and a seperate API server such as Parse. The benefits are: You get full SEO with a heavy client JavaScript site without having to do crazy things with PhantomJS or meta fragments. Hosting and operations become both cheap and doesn’t require a support team. Scaling out the system is mainly a bandwidth problem, and secondarily a API scaling problem for a subset of behavior.

Read more