Deploy Hugo website using Github pages

Hugo is one of the most widely used static site generators, and I found it to be a great tool to build my website. I knew about Github pages providing a custom domain for each account, so I chose it to deploy my website. Here's how you can deploy your Hugo website using Github pages as well.

Setting up the repositories

Build your Hugo website (if you're not familiar with the tool, here's the official quickstart guide). Push the complete website folder to a Github repository.
This is our source repository, containing the Hugo source files. It can be either public or private, but I would recommend to keep it private.

Next, create a Github repository named <your-username>.github.io, where <your-username> should be replaced by your Github account username (see Github pages).
This will be the URL for your website once deployed. This repository should be public.

In your source repository, in config.toml, add a baseurl field with your website URL.
For example:
baseurl = "https://importhuman.github.io"

Github workflow for deploying website

We need to add a Github workflow to our source repository, so the static pages are deployed to the public repository and our website can be viewed.

In the source repo, add the following workflow (with modifications, detailed below) in the .github/workflows folder.

name: Github Pages

on:
  push:
    branches:
      - main
  pull_request:

jobs:
  deploy:
    runs-on: ubuntu-20.04
    steps:
      - uses: actions/checkout@v2
        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.83.0'

      - name: Build
        run: hugo --minify

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          deploy_key: ${{ secrets.PRIVATE_KEY }}
          external_repository: <username/username.github.io>
          publish_dir: ./public

• "on" is the Github event that triggers the workflow. Here, it is triggered when a commit is pushed to the main branch, or a pull request is made.
• "hugo-version" specifies the Hugo version you want to build your website with. Here, it is '0.83.0'.
• The "deploy_key" field is required to deploy from our source repo to public repo (Detailed steps below).
• "external_repository" is the path to your public repo. In my case, it is importhuman/importhuman.github.io. It is important to include the username.
• "publish_dir" is the folder that contains the files we want to deploy. By default, static files in Hugo are stored in the ./public folder on running hugo -D. If you have modified this in your configuration, make the corresponding change in the workflow.

For more information about the actions used and their options, please see Hugo and Github pages on Github.

Adding keys

After adding the workflow and pushing to Github, we need to add keys to allow the workflow to run.

In the command line, run the following command to generate a pair of keys:

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

This will create private and public keys in files named deployment and deployment.pub respectively.

(This command uses the global git email on the computer. If you haven't set it before, you can do so by running git config --global user.email "youremail@yourdomain.com", or simply generate the keys by replacing $(git config user.email) with your email directly.)

Copy the private key from deployment, and in the Github source repository, navigate to Settings > Secrets > New repository secret. Add the private key and save it as PRIVATE_KEY. This is what we've referred to in our workflow.

Next, copy the public key from deployment.pub, and in the Github public repository, navigate to Settings > Deploy keys > Add deploy key. Add the public key and save it as PUBLIC_KEY.

(Source: bodunhu.com)

Other settings and configurations

By default, Github pages use Jekyll for building websites. To prevent this, add a .nojekyll file (blank, no content needed) in the public repository.

Finally, in the Github public repository, navigate to Settings > Pages. In the 'Source' section, select the gh-pages branch and / (root) folder and save.

And you're all set! Now pushing a commit or opening a PR on the source repo should automatically reflect the changes on your website!

Feel free to reach out in the comments or on Twitter if you have any doubts or issues :)