Skip to Content

Deploying Hugo site on GitHub Pages

ptags: github, hugo

There is an excellent GitHub Action to build and deploy a Hugo site to GitHub Pages by Ben Selby.

But, the problem is that the action requires Personal Access Token to operate which currently require classic token with a full access to all user repo. I’m not comfortable with that.

Another issue, it seems that it is created to deploy to another git repo as it nukes the target and retain only a single commit.

I will here describe a less intrusive way to post hugo site using GitHub Pages. For this I created a modified version of Ben’s action just by removing all git related publishing code. The action now merely downloads appropriate version of Hugo and do the build. The actual deploy is handled by official GitHub actions.

Workflow script is in most part generated by going to Settings->Pages and choosing GitHub Actions as source. There you have option to use Jekyll or deploy static pages produced by other static site builder. Choose the later and you will get the workflow config. There I just inserted a call to modified hugo builder. As of this writing you will get a workflow similar to this:

# Simple workflow for deploying static content to GitHub Pages
name: Deploy static content to Pages

on:
  # Runs on pushes targeting the default branch
  push:
    branches: ["main"]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow one concurrent deployment
concurrency:
  group: "pages"
  cancel-in-progress: true

jobs:
  # Single deploy job since we're just deploying
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
        with:
          submodules: true
      - name: Setup Pages
        uses: actions/configure-pages@v2
      - name: Hugo Deploy GitHub Pages
        uses: igordejanovic/hugo-deploy-gh-pages@main
        env:
          HUGO_VERSION: 0.105.0
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v1
        with:
          path: 'public'
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v1

Save this in .github/workflow/build-site.yaml in your Hugo git repo.

What this does is

  1. Checkout the source of the site.
  2. Do the setup.
  3. Call Hugo builder action which downloads Hugo and build the static pages.
  4. Upload public folder as a build artifact.
  5. Deploy uploaded artifact as a new site.

This will keep site repo clean. No deployment branches (like gh-pages), no public folder with built static pages etc. And, no need to setup and take care of Private Access Tokens.