Automatically deploy Hugo site to GitHub pages with actions

6 January 2023 (Updated: 20 July 2023)

Tags:

One of the big advantages with static sites are that you can host them almost anywhere. I have found that GitHub pages is one of the most convenient hosting solutions.

With the help of GitHub actions the deployment process can be completely automated. Push code to the repo and a minut later your site is updated.

The standard way to set it up was to build the site via an action to the “gh-pages” branch. GitHub would then run an extra action to take that content and deploy it to GitHub pages.

GitHub actions when deploying from branch. — GitHub actions when deploying from branch trigger an extra pages-build-deployment action.

This is no longer needed. You can now deploy directly to GitHub pages within your own action. See Configuring a publishing source for your GitHub Pages site - GitHub Docs.

This is the workflow I use for all Hugo sites I deploy. Add it to your Hugo site repos.

File: .github/workflows/pages.yaml

name: Deploy pages on push

# When the action should run. Here we specify it should run on push to main branch.
# We also allow for manually running the action with the empty "workflow_dispatch".
on:
  push:
    branches:
      - main

  workflow_dispatch:

# Set the needed permissions
permissions:
  contents: read
  pages: write
  id-token: write

# Cancel running deployments if a new one is issued.
concurrency:
  group: pages
  cancel-in-progress: true

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

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: "latest"
          extended: true

      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v3

      - name: Build
        run: hugo --baseURL "${{ steps.pages.outputs.base_url }}/"

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v1
        with:
          path: ./public

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2

Then go to “Settings -> Pages” for your repo. Set the “Source” to GitHub Actions".

GitHub pages settings — Deploying directly from action is in beta but works without issues in my experience.

Now you are done. The site will automatically build and deploy.

Updated: 20 July 2023
Created: 6 January 2023