benmatselby / hugo-deploy-gh-pages

📦 A GitHub Action to build and deploy a Hugo site to GitHub Pages

Hugo Deploy to GitHub Pages

This GitHub action will build your Hugo site, and then publish back to GitHub Pages.

Secrets

• TOKEN: A GitHub access token that can push to other repos, which in this case will be your GitHub pages repo. We cannot use GITHUB_TOKEN as defined here because it is a locally scoped token to a specific repo.

Environment Variables

• CNAME: Contents of a CNAME file.
• GITHUB_ACTOR: The name of the person or app that initiated the workflow. For example, octocat. See here.
• GO_VERSION: The version of Go you may want to install. This is not required for basic operation. Values should be in the format of 1.17.
• HUGO_ARGS: Arguments passed to hugo.
• HUGO_EXTENDED: If set to true, the extended version of Hugo will be used. Default is false.
• HUGO_PUBLISH_DIR: Specify if you do not use the Hugo default of public.
• HUGO_VERSION: This allows you to control which version of Hugo you want to use. The default is to pull the latest version.
• TARGET_BRANCH: This is the branch to push the public files e.g. docs. Default is main branch.
• TARGET_REPO: This is the repo slug for the GitHub pages site. e.g. benmatselby/benmatselby.github.io.

Example

name: Push to GitHub Pages on push to main
on:
  push:
    branches:
      - main

jobs:
  build:
    name: Deploy
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v1

      - name: Deploy the site
        uses: benmatselby/hugo-deploy-gh-pages@main
        env:
          HUGO_VERSION: 0.88.0
          TARGET_REPO: benmatselby/benmatselby.github.io
          TARGET_BRANCH: main
          TOKEN: ${{ secrets.TOKEN }}
          HUGO_ARGS: '-t academic'
          CNAME: benmatselby.github.io

This will:

• Clone the TARGET_REPO into the build folder.
• Commit the changes with the date as the git commit message.
• Push back to GitHub using the TARGET_BRANCH environment variable.

Testing

To test this action locally, you can run the following in your hugo site:

Build the docker image

docker build --pull --rm -f "Dockerfile" -t hugodeployghpages:latest .

Run the standard version of Hugo and the action.

# cd to your hugo site
docker run --rm \
  -eGITHUB_TOKEN \
  -eGITHUB_ACTOR \
  -eTARGET_REPO=benmatselby/benmatselby.github.io \
  -v "$(pwd)":/site/ \
  --workdir /site \
  hugodeployghpages

Run the extended version of Hugo, and the action.

# cd to your hugo site
docker run --rm \
  -eHUGO_EXTENDED=true \
  -eGITHUB_TOKEN \
  -eGITHUB_ACTOR \
  -eTARGET_REPO=benmatselby/benmatselby.github.io \
  -v "$(pwd)":/site/ \
  --workdir /site \
  hugodeployghpages

Tutorial

For an in depth tutorial, see this blog post. It is geared mostly at users of the Hugo Academic theme, but should be more broadly applicable.

hugo-deploy-gh-pages's Issues

Is it possible to change the default of Target repository to branch?

To avoid getting infinity loop between the publishing to master and deploying the github pages because there is a master branch push

Hugo's 'publishDir' prevents the Action to complete

I met this method of auto-publishing a few months ago and, back then, I tested it with a makeshift project using the most basic theme I've found on the Internet.

Then I kept on my project, developing my own theme 'til today, release day, the action failed several times in a row pointing me with the error /usr/bin/action.sh: line 83: cd: public: No such file or directory right after Hugo's compilation summary (number of pages, static files, time taken...)

I've tested many possibilities to fix this without understanding why the test repository worked and the real one didn't, 'til I decided to comment out the publishDir entry in my config.yaml that was pointing to ../some-other-folder used while developing with Hugo Server.

I don't know if you can make the Action workaround it, maybe creating a virtual copy of the config.yaml in the repository and manually removing that entry, who knows, I'm just posting here so anyone else in trouble has some info on how to fix that.

Thank you for your work :D

TARGET_REPO parameters

Does the target repository always a username?
What if I want to deploy my hugo pages in a project deployment rather than personal blog

Failed to read Git log: fatal: detected dubious ownership in repository at '/github/workspace'

Hello,

the action started to fail recently for one of our repos.

Building the Hugo site with: 'hugo '
Start building sites … 
hugo v0.98.0-...
ERROR 2022/12/20 10:14:35 Failed to read Git log: fatal: detected dubious ownership in repository at '/github/workspace'
To add an exception for this directory, call:
	git config --global --add safe.directory /github/workspace
Error: Error building site: logged 1 error(s)

I tried to reproduce it locally by checking out the code the way GitHub does and then running your action in a container as described in the README, but I haven't been successful so I don't have a clear reproducer for you.
But if you fork https://github.com/packit/status the https://github.com/packit/status/blob/main/.github/workflows/deploy-pages.yml should fail for you as well - if you change it to use your action instead of my fork and remove the if: condition.

I have been able to workaround the problem exactly the way the error message suggests, i.e. by adding
"git config --global --add safe.directory ${PWD}" to the action.sh.

See actions/checkout#766 for more info.

0.6 Release

Hi @benmatselby kindly let me know when are you going to release the 0.6 version
I can help by creating a similar documentation like how jwright wrote it :)

Thank you

Is it possible to push to Branch on target repository?

Failure to build current academic-kickstarter due to lack of hugo extended

When trying to deploy the current academic-kickstart repo, the action fails with an error that seems to indicate that Hugo Extended is required:

Error: Error building site: TOCSS: failed to transform "main_parsed.scss" (text/x-scss): resource "scss/scss/main.scss_6c95cc1249b26b124274204dbf970c34" not found in file cache
[...]

According to this issue, Hugo Extended does seem to be a prerequisite. However, in the current version of this action there does not seem to be a way to specify that Hugo Extended should be used.

failed to download modules: exec: "go"

Hi,

I've been using this action for a while, following the Tutorial. But after updating to a newer version of Wowchemy, I'm getting this error:

Error: failed to download modules: exec: "go": executable file not found in $PATH

I tried to install go in many different ways, for instance:

    - name: setup go
      uses: actions/setup-go@v1
      with:
        go-version: 1.16.x

But the error persists.

Do you have any idea about how to solve it?

Suggest do not use git diff

Refer to your code
https://github.com/benmatselby/hugo-deploy-gh-pages/blob/master/action.sh#L52

When I add new post or new image and run hugo, new file generated to public/, but it is not existed in target_repo(build/), so git diff --exist-code can not diff anything and exit with 0.

In my opinion, don't clone the target_repo, directly run

cd ${GITHUB_WORKSPACK}
hugo
rm -rf .git
cd public
git init
git add .
git commit -m 'Auto build'
git remote add origin $TARGET_REPO
git push -f origin master

if nothing to commit, git will exit itself. and the code in public has not worthy to keep in git