--- date: 2022-12-04 22:02:08-05:00 draft: false math: false medium_enabled: true medium_post_id: b08e82293bd2 tags: - Hugo title: Deploying my Hugo Website through GitHub Actions --- 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. ```yaml - name: Setup Hugo env: HUGO_VERSION: 0.105.0 run: | curl -L "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_${HUGO_VERSION}_Linux-64bit.tar.gz" --output hugo.tar.gz tar -xvzf hugo.tar.gz sudo mv hugo /usr/local/bin ``` ### Step 4: Build the 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. ```yaml - name: Build Hugo Website run: hugo ``` ### Step 5: Install the SSH key ```yaml - name: Install SSH Key run: | install -m 600 -D /dev/null ~/.ssh/id_rsa echo "${{ secrets.BUILD_SSH_KEY }}" > ~/.ssh/id_rsa echo "${{ secrets.HOST_KEY }}" > ~/.ssh/known_hosts echo "Host brandonrozek.com Hostname brandonrozek.com user build IdentityFile ~/.ssh/id_rsa" > ~/.ssh/config ``` 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 ```bash #!/usr/bin/env sh rsync -Pazc --exclude=*.bak --delete public/ build@brandonrozek.com:brandonrozek/ ``` 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. GitHub action in its entirety: ```yaml name: Build and Deploy Hugo Website on: workflow_dispatch: push: branches: main schedule: - cron: "21 11 * * *" jobs: build_and_publish: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v3 with: submodules: true fetch-depth: 0 - name: Git submodule update run: | git pull --recurse-submodules git submodule update --remote --recursive - name: Setup Hugo env: HUGO_VERSION: 0.105.0 run: | curl -L "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_${HUGO_VERSION}_Linux-64bit.tar.gz" --output hugo.tar.gz tar -xvzf hugo.tar.gz sudo mv hugo /usr/local/bin - name: Build Hugo Website id: build run: | hugo - name: Install SSH Key run: | install -m 600 -D /dev/null ~/.ssh/id_rsa echo "${{ secrets.BUILD_SSH_KEY }}" > ~/.ssh/id_rsa echo "${{ secrets.HOST_KEY }}" > ~/.ssh/known_hosts echo "Host brandonrozek.com Hostname brandonrozek.com user build IdentityFile ~/.ssh/id_rsa" > ~/.ssh/config - name: Deploy run: ./deploy.sh ```