For the start, you will require two repositories: one to store your Hugo project, and the other to host the GitHub page with the static files generated by Hugo.

Configuring GitHub Pages

GitHub Pages is a straightforward solution for hosting a static website. You can find more information on how to set up your GitHub Pages in the relevant documentation.

To give GitHub Actions permission to write to your GitHub Pages repository, you will need to create a secret key pair. Run the following command in your terminal:

ssh-keygen -t rsa -b 4096 -C "$(git config user.email)" -f gh-pages -N ""

This will generate two files, gh-pages and gh-pages.pub, in your current directory.

Next, navigate to the settings in your GitHub Pages repository, select Deploy keys, and add a new deploy key. Copy and paste the contents of the gh-pages file generated in the previous step into the new key, and save it. The GitHub Pages repository does not require any further configuration unless you want to confirm that your website is available before proceeding to the next step.

Config Hugo repository

In your repo that you keep your Hugo project, open the settings and from the sidebar select Secret and Variables -> Actions and add a new secret key. this time copy and past the content of gh-pages.pub and give it a name. Remember what name you’re giving it because we need it for the next step. I chose ACTION_DEPLY_KEY.

Now we create a file under .github/workflow/hugo.yaml and add the following content into it:

name: GitHub Pages

on:
  push:
    branches:
      - master  # Set a branch name to trigger deployment
  pull_request:

jobs:
  deploy:
    runs-on: ubuntu-22.04
    permissions:
      contents: write
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
    steps:
      - uses: actions/checkout@v3
        with:
          submodules: true  # Fetch Hugo themes (true OR recursive)
          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod

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

      - name: Build
        run: hugo --minify && echo "keyboardsmash.dev" > public/CNAME

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
          external_repository: smoqadam/keyboardsmash.github.io
          publish_branch: main  # default: gh-pages
          publish_dir: ./public

There are several key considerations to keep in mind:

  • The GitHub Actions workflow checks the branch specified on line 6 for any changes. Ensure that you change it if you are using a branch other than master.

  • The Setup Hugo step (line 22) uses peaceiris/actions-hugo@v2 to install Hugo on the GitHub Actions virtual machine. The only important aspect to note is hugo-version, which must match the version of Hugo you are using.

  • In the next step, generate the static files by running the hugo –minify command. If you don’t want to minify your content, remove the –minify parameter. If you have a custom domain for your GitHub pages repository, create a file called CNAME with your domain name in it. This is because every time you run the hugo command, the contents of the ./public folder are replaced, including the CNAME file.

  • In the Deploy step, you must use the name of the deploy key that you generated earlier. Additionally, you must specify external_repository with the name of your GitHub pages repository. If you are using a branch other than main in your GitHub pages, change publish_branch.

  • The publish_dir is set to ./public by default.

Once you have made these changes, save the file, and you will see an action running under the Actions tab.