In this blog post, we will discuss how to deploy a Hugo static site to GitHub Pages using GitHub Actions. GitHub Actions is an automation feature provided by GitHub that allows you to create custom software development workflows directly in your GitHub repository. By using GitHub Actions, you can automate the process of building and deploying your Hugo static site to GitHub Pages with ease.

Configuring GitHub Pages Settings

Before you can successfully deploy your Hugo static site to GitHub Pages using GitHub Actions, you need to configure the GitHub Pages settings for your project.

  1. Go to your GitHub project page and click on the “Settings” tab in the top right corner.
  2. Scroll down to the “Pages” section.
  3. In the “Build and deployment” settings, locate the “Source” dropdown menu.
  4. Select “GitHub Actions” from the available options. This tells GitHub Pages to use the artifacts generated by GitHub Actions for deployment.

Now that you’ve configured your GitHub Pages settings, your site will be deployed using the workflow defined in the hugo.yaml file.

Setting Up Your GitHub Pages Workflow

To set up a GitHub Pages workflow with Hugo and GitHub Actions, follow these steps:

  1. Create a new file named hugo.yaml in the .github/workflows/ directory of your Hugo site’s repository.
  2. Copy the following YAML configuration into the hugo.yaml file:
name: Deploy Hugo site 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 only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false

# Default to bash
defaults:
  run:
    shell: bash

jobs:
  # Build job
  build:
    runs-on: ubuntu-latest
    env:
      HUGO_VERSION: 0.111.3
    steps:
      - name: Install Hugo CLI
        run: |
          wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \
          && sudo dpkg -i ${{ runner.temp }}/hugo.deb          
      - name: Install Dart Sass Embedded
        run: sudo snap install dart-sass-embedded
      - name: Checkout
        uses: actions/checkout@v3
        with:
          submodules: recursive
          fetch-depth: 0
      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v3
      - name: Install Node.js dependencies
        run: "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true"
      - name: Build with Hugo
        env:
          # For maximum backward compatibility with Hugo modules
          HUGO_ENVIRONMENT: production
          HUGO_ENV: production
        run: |
          hugo \
            --gc \
            --minify \
            --baseURL "${{ steps.pages.outputs.base_url }}/"          
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v1
        with:
          path: ./public

  # Deployment job
  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

This configuration file sets up a workflow that builds your Hugo static site and deploys it to GitHub Pages when you push to the main branch or run the workflow manually from the Actions tab.

Conclusion

With the addition of configuring GitHub Pages settings in your project and using the provided hugo.yaml workflow configuration, you can easily automate the process of building and deploying your Hugo static site to GitHub Pages. By utilizing GitHub Actions, you can focus on creating content and making updates to your site without having to manually deploy it each time. This setup also allows you to take advantage of the built-in CI/CD capabilities provided by GitHub Actions, further improving your development workflow.

Source code : https://github.com/hobbyworker/hugo-demo

Demo : https://hobbyworker.me/hugo-demo