Deploying a Hugo site with Github Actions

This website is based on the Hugo static site generator. The content itself is stored in a private GitHub repository. A pretty standard setup, but I always felt it was a bit of a hassle to push content to the live website. That's served on a Linux VM running Caddy. To deploy, I needed to run Hugo on my local machine to generate the website and then I need to execute rsync to deploy them to the webserver.

With scheduled posts, it's a bit more annoying as you need to deploy the site again after the date on which the post is scheduled to be posted. That's something I always tend to forget.

Wouldn't it be easier if I just had to commit the content to the git repository and that all the rest would just happen automagically?

We'll, it's not that hard to automate thanks to GitHub actions. The prerequisites are the only tricky part in the whole setup.

Before we can define the action, we first need to get our SSH private key and the fingerprint of the server we want to send the data to.

To get the SSH private key, you can just execute:

$ cat ~/.ssh/id_rsa
-----BEGIN RSA PRIVATE KEY-----
...
-----END RSA PRIVATE KEY-----

To get the fingerprints, we can use the ssh-keyscan function using the hostname we intend to deploy to:

$ ssh-keyscan www.yellowduck.be
# www.yellowduck.be:22 SSH-2.0-OpenSSH_7.2p2 Ubuntu-4ubuntu2.8
www.yellowduck.be ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAGyGeW/A/d5uzUzvmLN0wbkA13OzAGfm+Qzsi0UfAWX
# www.yellowduck.be:22 SSH-2.0-OpenSSH_7.2p2 Ubuntu-4ubuntu2.8
www.yellowduck.be ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCfGYe98PCJa0eQGkER6KLQOQBlo9Y3D1iVjvW+AwJUmswjjyniJDkynylquoL2vkEu3P0fgMYDoVwCbwRkbRtgmHyBlHQbbgnAkYnG4QUwglfDe0d0k668c9ti3kfgF2M+s0disTdgGykUWcLXs02n4Fsz6id3/HNRCI59roNxMt0VioE3ZayMaRzT6JCYhp7Zf/YiMfWphCeRF49jKs8BoRqZc5EbQAlTePBtw4PS10AYAWLawV42kt7wetxevTVQoUJfljCzUE28at7BRHOgy/19tJ+UaokCPba7mL4pvs6348pbPpPHluynkcD+KNFoM3I/KCyhUq2MBhM+k6Ab
# www.yellowduck.be:22 SSH-2.0-OpenSSH_7.2p2 Ubuntu-4ubuntu2.8
www.yellowduck.be ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBMkVOX5JpzQmtUIhDPWu/+A0UjczIZ0V4Gzdbet5lB4Ee6mcQrvQ//g+pEsfbAFMIOSw2h75wykNoZ4r5y0SZVo=

Once we have these, we'll store them as secrets in our GitHub repository. To do so, browse to the settings page of your repository on GitHub and select "Secrets". You'll need to add two secrets:

• SSH_KEY which needs to contain your SSH private key
• KNOWN_HOSTS which needs to contain the output of the ssh-keyscan command

Now that we have that in place, all which is left is to define the GitHub action itself. First, start with creating a new file in your repository unde .github/workflows/deploy.yaml.

The fill it with the actual action definition:

 1name: Build and Deploy
 2
 3on:
 4  push:
 5    branches: [ master ]
 6  pull_request:
 7    branches: [ master ]
 8  schedule:
 9    - cron:  '0 * * * *'
10
11jobs:
12  build:
13    name: Build and Deploy
14    runs-on: ubuntu-latest
15    steps:
16
17    - name: Install SSH key
18      uses: shimataro/ssh-key-action@v2
19      with:
20        key: ${{ secrets.SSH_KEY }}
21        name: id_rsa
22        known_hosts: ${{ secrets.KNOWN_HOSTS }}
23
24    - name: Checkout code
25      uses: actions/checkout@v2
26
27    - name: Setup Hugo
28      uses: peaceiris/actions-hugo@v2
29      with:
30        hugo-version: '0.69.2'
31
32    - name: Build
33      run: hugo --minify
34
35    - name: Copy to webserver
36      run: rsync --delete -rvzh ./public/ user@www.yellowduck.be:/var/www/html/yellowduck.be/

Once you commit that, a number of things will happen. Everytime you commit or merge to the master branch, the action will run. Additionally, it will run once on an hour as well with the contents of the master branch. I did both to ensure that when I commit something, an update is deployed immediately. To tackle the scheduled posts, I run the action hourly.

Let's have a look at what the action does.

The option name just defines the name of the action:

1name: Build and Deploy

The on option defines when the action is triggered:

1on:
2  push:
3    branches: [ master ]
4  pull_request:
5    branches: [ master ]
6  schedule:
7    - cron:  '0 * * * *'

When the action runs, it just performs a single job called Build and Deploy. It's using a Ubuntu Linux container to run the job on:

1jobs:
2  build:
3  name: Build and Deploy
4  runs-on: ubuntu-latest

The job itself consists of several steps.

The first step is to get the SSH key installed by using the Install SSH Key action:

1- name: Install SSH key
2  uses: shimataro/ssh-key-action@v2
3  with:
4  key: ${{ secrets.SSH_KEY }}
5  name: id_rsa
6  known_hosts: ${{ secrets.KNOWN_HOSTS }}

It's using the secrets we defined earlier to do it's work.

The next step is to checkout the code from the git repository:

1- name: Checkout code
2  uses: actions/checkout@v2

After the checkout, we use the Hugo action to install Hugo on the container:

1- name: Setup Hugo
2  uses: peaceiris/actions-hugo@v2
3  with:
4    hugo-version: '0.69.2'

With Hugo installed, we can then build the minified version of the site:

1- name: Build
2  run: hugo --minify

Last but not least, we can use rsync to deploy the site:

1- name: Copy to webserver
2  run: rsync --delete -rvzh ./public/ user@www.yellowduck.be:/var/www/html/yellowduck.be/

After committing this to the repo, you can use the "Actions" tab in your repository to monitor what's happening…

If the action happens to fail, you'll be notified by email.