For the longest time I've held out on deploying my website through GitHub actions. My rationale at the time was:
> If I have to execute `git push`, I might as well run a `./sync` script afterwards.
What convinced me otherwise is automated commits. I currently have GitHub actions that sync my [Mastodon toots](/toots) and [iNaturalist observations](/observations). As part of the sync process, a git commit is made. This commit should then trigger a site rebuild.
How do we create a GitHub action that builds a Hugo website and deploys it via `rsync`? The rest of this post will go over the components of the GitHub action that triggers when I update my website.
## Triggers
I currently have three triggers for my deployment GitHub action:
- Manual (`workflow_dispatch`)
- Pushes to the `main` branch
- Daily schedule via `cron`
```yml
on:
workflow_dispatch:
push:
branches: main
schedule:
- cron: "21 11 * * *"
```
## Steps
I call my job `build_and_publish` and have it run on top of the latest Ubuntu image.
```yml
jobs:
build_and_publish:
runs-on: ubuntu-latest
```
### Step 1: Checkout the Repository
Here we can rely on Github's `checkout` action to provide the latest version of the code.
```yml
steps:
- name: Checkout
uses: actions/checkout@v3
with:
submodules: true
fetch-depth: 0
```
Since my website relies on submodules, we need to make sure that its included in the checkout. The `fetch-depth` flag denotes how many commits to retrieve. By default (`fetch-depth: 1`) it only fetches the latest commit, however setting it to `0` retrieves all commits. This is needed for Hugo's last modified feature to work.
### Step 2: Update the submodules
Even though we checked out the whole repository with its associated submodules, they may be out of date. This step makes sure that we're using the latest version of the submodule.
```yaml
- name: Git submodule update
run: |
git pull --recurse-submodules
git submodule update --remote --recursive
```
### Step 3: Setup Hugo
Since Hugo is a static binary, we can pull it straight from their website.
We can use a separate step to build the website. This along with the deployment are among the few places where this script can fail, so it's nice to separate it out in case.
At this point in our script we need to handle [secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets). The post I linked to will likely have the most up to date information, but as of this time of writing, you can add secrets by going to the `Settings` tab of the repository. A secret is a key-value pair, therefore to access your secret in the GH action, you need to reference the key.
```yaml
${{ secrets.YOUR_KEY_HERE }}
```
We need secrets for the SSH key used to deploy the website and the known hosts file so that I don't have to do host verification. The first line ensures that the permissions of the SSH key is correct, and the last line makes it so that the `rsync ` command within my `sync.sh` script is simpler. I use my `sync.sh` not only in the next step of this action but on my own machine which has a different config associated with it.
### Step 6: Deployment
```yaml
- name: Deploy
run: ./deploy.sh
```
In my repository there is a `deploy.sh` with the following contents
This syncs everything within the `public` build folder up to my webserver excluding files ended in `.bak` and removing any files on the webserver that aren't in the build folder.
## Conclusion
Other than the `checkout` action, each step does not depend on an external library to provide the functionality. I think it's important to implement each of the steps ourselves, as opposed to relying on a `hugo` GH action library or a `SFTP` library. Not only does this safeguard us against supply side attacks, it also makes these actions more portable. I am not counting on GitHub to always allow the usage of their build infrastructure for free.
