Use Hugo with Github Pages and CircleCI

3/28/2019 tutorialwebhugocircleci

This tutorial is to teach you how to make youre own hugo-generated static site served by Github Pages, within a single repo.

# Prerequisites

  1. Github & CircleCI account
  2. Newly-generated SSH key pair for safety reasons(see here (opens new window))
  3. Hugo installed locally

# Dive in

Generate site source with hugo command:

hugo new site <SITE_NAME>
1

Create a repo for your site: <SITE_NAME>.github.io(Be aware: this tutorial uses User/Organization Pages rather than Project Pages, see here (opens new window)), clone it, and create a new branch called source(whatever you like):

git clone https://github.com/<USERNAME/ORGANIZATION>/<SITE_NAME>.github.io.git
cd <SITE_NAME>.github.io
git checkout -b source
1
2
3

Copy everything from the folder created by hugo above into repo:

mv ../<SITE_NAME>/* .
1

Go to circleci.com (opens new window) and add your <SITE_NAME>.github.io project. Goto Project Settings, under SSH Permissions, add SSH private key you just generated(see here (opens new window)), copy the Fingerprint for use below.

Go to Github your project settings, under Deploy Key, add SSH public key you just generated.

Create config file for CircleCI:

mkdir .circleci
cd .circleci
touch config.yml
1
2
3

config.yml(Edit it with your own information):

version: 2.0

jobs:
    build:
        docker:
            - image: felicianotech/docker-hugo:latest
        working_directory: ~/<SITE_NAME>.github.io
        steps:
            - add_ssh_keys:
                fingerprints:
                    - "<FINGERPRINT_YOU_JUST_COPIED"
            - checkout
            - run:
                name: Get current site
                working_directory: ~/
                command: git clone -b master [email protected]:<USERNAME/ORGANIZATION>/<SITE_NAME>.github.io.git public
            - run:
                name: Generate site
                working_directory: ~/<SITE_NAME>.github.io
                command: HUGO_ENV=production hugo -d ~/public
            - deploy:
                name: Deploy to Github Pages
                working_directory: ~/public
                command: |
                    git config credential.helper 'cache --timeout=120'
                    git config user.email "<YOUR_EMAIL>"
                    git config user.name "Deployment Bot"
                    git add .
                    git commit --allow-empty -m "Trigger deployment"
                    git push -q [email protected]:<USERNAME/ORGANIZATION>/<SITE_NAME>.github.io.git master

workflows:
  version: 2
  main:
    jobs:
    - build:
        filters:
          branches:
            only: source
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

Now push your files to Github:

git add .
git commit -m "first commit"
git push origin source
1
2
3

For every time you push to the source branch, CircleCI will always trigger a hugo generation to the master branch, where the site's static file generated by Hugo is placed.

Wait for CircleCI's job done, then visit <SITE_NAME>.github.io and enjoy!

Last Updated: 5/6/2021, 3:44:21 AM