Deploy Hugo project to GitHub Pages with GitHub Actions

tips & tricks
1

(1) Add ssh deploy key

Generate your deploy key with the following command.

ssh-keygen -t rsa -b 4096 -C "$(git config user.email)" -f gh-pages -N ""
# You will get 2 files:
#   gh-pages.pub (public key)
#   gh-pages     (private key)

Next, Go to Repository Settings

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

(2) Create your workflow

:star: Repository type - Project

An example YAML file (.github/workflows/gh-pages.yml) with Hugo action.

name: github pages

on:
  push:
    branches:
    - master

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

    - name: Setup Hugo
      uses: peaceiris/actions-hugo@v2.2.0
      with:
        hugo-version: '0.58.3'

    - name: Build
      run: hugo --gc --minify --cleanDestinationDir

    - name: Deploy
      uses: peaceiris/actions-gh-pages@v2.4.0
      env:
        ACTIONS_DEPLOY_KEY: ${{ secrets.ACTIONS_DEPLOY_KEY }}
        PUBLISH_BRANCH: gh-pages
        PUBLISH_DIR: ./public

The above example is for Project Pages sites. (<username>/<project_name> repository)

:star: Repository type - User and Organization

For User and Organization Pages sites (<username>/<username>.github.io repository),
we have to set master branch to PUBLISH_BRANCH.

on:
  push:
    branches:
    - source  # default branch

PUBLISH_BRANCH: master  # deploying branch

For more details, go to repositories.

10 Likes
2

Check the latest version of peaceiris/actions-hugo

From v2.0.0, this Hugo action migrated to a JavaScript action. We no longer build or pull a Hugo docker image. Thanks to this change, we can complete this action less than 4 sec . (Docker base action was taking about 1 min execution time to build or pull.)

1 Like
3

The GitHub Actions became GA now! Enjoy Hugo on GitHub Actions.
ʕ◔ϖ◔ʔ

4

Here is the new workflow with peaceiris/actions-gh-pages v3.

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

This action has been migrated to a TypeScript Action. Your job will complete faster than v2.

5

Here is the latest example workflow.

name: github pages

on:
  push:
    branches:
      - master

jobs:
  deploy:
    runs-on: ubuntu-18.04
    steps:
      - uses: actions/checkout@v2
        with:
          submodules: true

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: '0.67.1'

      - name: Build
        run: hugo --minify

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

This Hugo setup action was featured by GitHub. Thank you all!
ʕ◔ϖ◔ʔ

1 Like
7

This topic was automatically closed 2 days after the last reply. New replies are no longer allowed.