Deploy Hugo website using Github pages
Tags: hugo, githubpages, website, deployment
Published: 2021-09-27 09:33:08

[Hugo](https://gohugo.io/) 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](https://pages.github.com/) 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](https://gohugo.io/getting-started/quick-start/)). 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](https://pages.github.com/)).
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.

```yaml
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](https://github.com/peaceiris/actions-hugo) and [Github pages](https://github.com/peaceiris/actions-gh-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](https://www.bodunhu.com/blog/posts/deploy-hugo-site-to-github-pages/))

## Other settings and configurations

By default, Github pages use [Jekyll](https://jekyllrb.com/) 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](https://www.twitter.com/importhuman) if you have any doubts or issues :)