Josh Gerdes

Over the years I have tried many static site generators to help manage my personal site and other projects.

Recently, I decided I wanted to find a setup that utilized github pages and did not rely on any local tooling for building or deploying my site.

I really liked how easy it was to use Hugo and once I found this great little project GitHub Actions for Hugo I knew I had a solution.

Here are some instructions detailing how I setup my site. You can find more details in the Getting Started section of the GitHub Actions for Hugo project.

1. Generate a SSH deploy key

Create your deploy key with the following command:

ssh-keygen -t rsa -b 4096 -C "$(git config user.email)" -f gh-pages -N ""

This will generate 2 files:

• gh-pages.pub (public key)
• gh-pages (private key)

Next, go to the github repository Settings and do the following:

• Go to Deploy Keys and add your public key with Allow write access checked
• Go to Secrets and add your private key as ACTIONS_DEPLOY_KEY

Your repository should allow actions to run workflows now.

2. Create a source branch

Create a source branch in your repository. In the setup you will have 2 branches master and source where source contains all of your source files and master is the location where your built site files are deployed and served up.

3. Create a workflow

Go to the github repository Settings and under Actions turn on Enable local and third party Actions for this repository.

Next, in the new source branch create the following file: .github/workflows/main.yml.

Here is an example that I am using for this site:

name: github pages

on:
  push:
    branches:
      - source

jobs:
  build-deploy:
    runs-on: ubuntu-18.04
    steps:
      - uses: actions/checkout@master

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: "latest"

      - name: Build
        run: hugo --gc --minify --cleanDestinationDir
      
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v2
        env:
          ACTIONS_DEPLOY_KEY: ${{ secrets.ACTIONS_DEPLOY_KEY }}
          PUBLISH_BRANCH: master
          PUBLISH_DIR: ./public

4. Push your Hugo project

Now you can commit and push your hugo project to the source branch of your repository. This should trigger the new workflow for the new action which will build and deploy your site to the master branch.