# Motivation

To test PRs on the upstream of a Hugo theme by setting up a testing branch.

# Goal

To deploy a forked GitHub repo for a Hugo theme with exampleSite to GitHub Pages using GitHub Actions.

The whole article is based on [my fork of Hugo Future Imperfect Slim][re

# Difficulties

I had failed for about ten times before I got the job done.

1. Generating a theme’s exampleSite is quite tricky due to the difference in file structure. I used to preview that by

cd exampleSite
hugo server --themesDir=../..


Running hugo server --themesDir .. --source exampleSite doesn’t work: .. has to be replaced with ~ so that the command works—that doesn’t work well on remote hosts when the current working path varies from host to host.

2. As a result, I tried to navigate to the parent directory with ${$(pwd)%/*}. That worked well on local Linux shells, but I ran into a bad substitution error. Luckily I found the above linked Stack Overflow question useful.

3. I got lost by switching between GitHub Actions for GitHub Pages and GitHub Actions for Hugo. With the idea that GitLab CI/CD can be migrated to GitHub Actions, I confused GitLab CI/CD’s pages.only with GitHub Actions' on.push.branches. I jumped to the precautions for first deployment a few times and I mistakenly thought that the source code was on the gh-pages branch. In fact, GitHub Actions takes a branch not named as gh-pages, and generates the static site on gh-pages. The error message "You deploy from gh-pages to gh-pages" was clear enough, so I fixed this quickly.

4. After that, GitHub Actions showed a green tick, indicating that the deploy was successful. I configured my repo to use gh-pages for GitHub Pages. However, when I navigated to the corresponding GitHub Pages, I got a 404 error. gh-pages had one single empty file: .nojekyll. It took me an hour to discover this line on the runner:

cp: no such file or directory: /home/runner/work/hugo-future-imperfect-slim/hugo
-future-imperfect-slim/public/*


I then navigated up to find the command used for the build.

hugo --themesDir "\${PWD%/*}" --source exampleSite --minify


I adapted this to my Zsh, and I found that the output was placed under exampleSite/public/. After the correction of publish_dir in GitHub Actions config, everything works.