GitHub Pages

This document ilustrates how to setup GitHub Pages using Hugo as website generator and GitHub’s Actions to automate the deployment process.

There are different alternatives to setup GitHub pages, the one used in here is a project pages using gh-pages branch, the advantages are:

It keeps your source and generated website in different branches and therefore maintains version control history for both.
It uses the default Hugo’s public folder.

So basically this project’s repository has the following branches:

master: Hosts the source code of the project under the docs/ folder.
gh-pages: Hosts the static assets generated by hugo.

Step 1: Structure

# Docs folder
mkdir docs && cd docs
hugo new site .
git add .
git commit -m "Adds initial hugo site"
git push origin master

# gh-pages branch
git checkout --orphan gh-pages
git reset --hard
git commit --allow-empty -m "Initializing gh-pages branch"
git push origin gh-pages

Step 2: Generate a SSH key.

ssh-keygen -t rsa -f hugo -q -N ""

This will generate the files: hugo and hugo.pub which will be needed for the next steps.

Step 3: Add a deployment key

Navigate to your GitHub’s repository settings and under Deploy keys add a new one using the content of the hugo.pub SSH key generated in the previous step.

Make sure the Allow write access is checked, otherwise the GitHub’s Action won’t be able to push changes.

Step 4: Create a secret

Navigate to you GitHub’s repository settings and under Secrets add a new one using the content of the hugo SSH private key generated in the step 2.

Step 5: Add the GitHub’s Action.

Create the needed directory in the hugo branch:

mkdir -p .github/workflows

Add a new file in the path .github/workflows/gh_pages.yml with the following content:

on:
  push:
    paths:
      - 'docs/**'
      - '.github/workflows/hugo.yml'

name: Hugo

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v1
    - name: Installs hugo
      run: |
        cd /tmp
        wget https://github.com/gohugoio/hugo/releases/download/v0.57.0/hugo_0.57.0_Linux-64bit.deb
        sudo dpkg -i hugo_0.57.0_Linux-64bit.deb
        hugo version

    - name: Build hugo site
      run: |
        cd docs
        rm -rf public
        git worktree add -b gh-pages public origin/gh-pages
        hugo

    - name: Configure git and deployment key
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        GITHUB_DEPLOY_KEY: ${{ secrets.WORKDAY_GH }}
      run: |
        mkdir /home/runner/.ssh
        ssh-keyscan -t rsa github.com >/home/runner/.ssh/known_hosts
        echo "${GITHUB_DEPLOY_KEY}" > /home/runner/.ssh/id_rsa && \
        chmod 400 /home/runner/.ssh/id_rsa
        git remote set-url origin git@github.com:iris-garcia/workday.git
        git config --global user.name "GitHub Action"
        git config --global user.email "action@github.com"

    - name: Commit and push changes to gh-pages
      run: |
        cd docs/public
        git add .
        git commit -m "Publishing to gh-pages branch"
        git push origin gh-pages

Replace the origin’s remote with your repository.

Finally commit and push the changes (which should trigger already the Action).

git add .github/workflows/gh_pages.yml
git commit -m "Adds GitHub's Action to build hugo site."
git push origin master

Step 5: Verify the Action

If everything went well you should already have your site updated and a new commit to the gh-pages branch.

You can also see the output of the Action navigating to the Actions section of your repository.