Automatic Build and Deploy using GitHub Actions

I’m using GitHub Pages to host this site. I started by building the site locally, and pushing the /public directory to my gh-pages branch on GitHub. (See these instructions on the Hugo website.) GitHub provides native support for building Jekyll sites, but does not have native support for Hugo. Nonetheless, using GitHub Actions, I can build and deploy my Hugo site automatically when I push new content to the main branch of my GitHub repository.

Getting started

Rename master to main

First, rename local branch.

cd ~/Sites/pymol-notes
git branch -m master main
git status
On branch main
nothing to commit, working tree clean

Next, rename remote branch.

git push -u origin main
git push origin --delete master

Because I am the solo developer on this project and I have a single local repository, I don’t have to do anything else.

Automate the build and deploy workflow

First, create a .github/workflows/ directory in your project root.

Next, create a gh-pages.yaml file in the .github/workflows/ directory that has the following contents.

name: Build and Deploy

on:
  push:
    branches:
      - main

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
    - name: Checkout main
      uses: actions/checkout@v1
      with:
        submodules: true

    - name: Hugo Deploy GitHub Pages
      uses: benmatselby/hugo-deploy-gh-pages@master
      env:
        HUGO_VERSION: 0.75.0
        TARGET_REPO: dgoppenheimer.github.io/pymol-notes/
        TOKEN: ${{ secrets.EXAMPLE_TOKEN }}

Let’s test this.

hugo new introduction/test-page.md

Results

No joy.

Here is a nice tutorial:

Hugo: Deploy Static Site using GitHub Actions

And another set of instructions that uses a similar .yml file from peaceiris:

Deploy Hugo project to GitHub Pages with GitHub Actions

I had success using the peaceiris actions

Here is the gh-pages.yml file that I used:

name: github pages

on:
  push:
    branches:
      - main  # Set a branch to deploy

jobs:
  deploy:
    runs-on: ubuntu-18.04
    steps:
      - uses: actions/checkout@v2
        with:
          submodules: true  # Fetch Hugo themes (true OR recursive)
          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: '0.75.1'
          # extended: true

      - name: Build
        run: hugo

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.EXAMPLE_TOKEN }}
          publish_dir: ./public

Note: I removed –minify from run: hugo, otherwise, my svg logo was not visible.

Great. Now I can work on a page, save it and do the following to update the site:

cd ~/Sites/pymol-notes
git status
git add .
git commit -m "updated site, added a page, corrected typos"
git push origin main