How to create a static website with Hugo and deploy it to your web hosting server

This article describes how to create and update a website using Hugo and Github actions, so that it is automatically deployed to your (shared) web hosting whenever you make and publish changes to the code.

Hugo is a popular open-source static site generator written in the Go programming language. A Hugo site is configured using YAML files, and the content is written in Markdown syntax.

Github Actions allow you to automate, customize, and execute your software development workflows right in your repository. You can discover, create, and share actions to perform any job you’d like, including CI/CD, and combine actions in a completely customized workflow.

Prerequisites

• A website made with Hugo (see Hugo Quick Start)
• The code of your website should be versioned in a Git repository and published to Github.
• A web hosting server which can be connected to by SSH.

To create the files for your static website, run the command hugo in the repository with your website content. This will compile the content, together with the selected theme, into a completly static website which is placed in the folder ./public.

Configure authentication via SSH

We will use SSH for file transfer.

In order for Github to connect to your web hosting server, we need to create a public/private keypair for SSH to ensure proper authentication.

Generate a public/private key pair (we use the file name github.key in this example):

ssh-keygen -b 2048 -t rsa -f github.key -q -N ""

OpenSSH has been added to Windows 10 as of autumn 2018, so the above command is supposed to work on both Linux/Unix and Windows systems.

Then copy the public key to the destination server (we use the hostname example.com and the username user in this example):

Linux/Unix:

ssh-copy-id -i github.key user@example.com

Windows:

type github.key.pub | ssh user@example.com "cat >> .ssh/authorized_keys"

The SSH private key, as well as the username and the hostname of the server should be stored as encrypted secrets in your Github project.

Go to your project on Github and navigate to Settings -> Secrets. Add the following secrets:

• HOST: example.com (replace with your web hosting server name)
• SSH_USER: user (replace with your web hosting user)
• SSH_PRIVATE_KEY: paste the content of your private key file

To get the private key file content, you can use the following command:

Linux/Unix:

cat github.key

Windows:

type github.key

Add Github action

We will create a Github action workflow which will:

• checkout your repository
• checkout and update your Hugo theme (which is usually added as a Git submodule)
• Initialize Hugo
• Run a build with Hugo
• Copy the contents of Hugo’s output directory to your web hosting server using SSH

Add the following content to a file .github/workflows/main.yml in the directory of your Hugo website.

name: Deploy to web hosting
on: push
jobs:
  deploy:
    runs-on: ubuntu-18.04
    steps:
      - name: Git checkout
        uses: actions/checkout@v2

      - name: Update theme
        run: git submodule update --init --recursive

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

      - name: Build
        run: hugo --minify

      - name: Deploy to web hosting server
        uses: garygrossgarten/github-action-scp@release
        with:
          local: ./public
          remote: path/to/your/webroot/
          host: ${{ secrets.HOST }}
          username: ${{ secrets.SSH_USER }}
          privateKey: ${{ secrets.SSH_PRIVATE_KEY }}

Observe the placeholders for your Github secret values. Set the value of the remote variable according to your web hosting configuration (e.g. public_html/).

Add the workflow file to git, commit and push.

git add .github/workflows/main.yml
git commit -m "Added Github action workflow"
git push

Github will now build and publish your website whenever you push any changes. After some minutes, the new site should be available at your web hosting.

See the Actions tab in your Github repository page for the status of your Github actions. You will also receive an e-mail to the address registered with your account should the Github action fail.