Publish Hugo site with Github Actions

25 Apr, 2022
2 min read

Thanks aneesahammed’s blog, I finally made it. Now my hugo site (this blog) has used the Github Actions to publish to Github Pages.

My Hugo site workspace is in a private github repository and my pulished site is in a public repository. Most of the article about publishing Hugo site and Github pages are talking about the same github repository with diffrent branch. Then finally I found aneesahammed’s blog and this is exactly what I need.

This is an example .github/workflows/gh-pages.yml :

(last updated: 2024-05-02).

Remember to setup the GHPAGE_TOKEN under your workspace repository settings/secrets/actions -> Repository secrets with the name GHPAGE_TOKEN.

name: GitHub Pages

on:
  push:
    branches:
      - master  # Set a branch to deploy
  pull_request:

jobs:
  deploy:
    runs-on: ubuntu-latest
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
    steps:
      - uses: actions/checkout@v4
        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@v3
        with:
          hugo-version: '0.119.0'
          extended: true

      - name: Build
        run: hugo --minify

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          external_repository: yourname/yourname.github.io
          publish_branch: master
          personal_token: ${{ secrets.GHPAGE_TOKEN }}
          user_name: yourname
          user_email: yourname@yourdomain.com
          publish_dir: ./public

And this is the tips for using the git submodule for the hugo themes.

when you want to use a hugo theme, do remember to use the theme in a git submodule mode. This is the document from the theme hyde-hyde

# Add hyde-hyde as a submodule
$ git submodule add https://github.com/htr3n/hyde-hyde.git themes/hyde-hyde

then if you check out your hugo workspace git repository in another work station, use these commands to update the themes:

git submodule init
git submodule update
git submodule update --remote --merge