In this guide we will go through the steps required to deploy a static site generated by hugo using github actions. Hugo is a tool used to generate static files. You can write the content using markdown and hugo will compile it to static html files that can be served. It is written using golang.

You can use Github Actions to deploy your site. When you push a commit into Github, you would want Github Actions to build your site and deploy to your cloud server.

# Github Actions

Github actions is a github service that allows you to automate any part of your development workflow (testing, deploying) based on github events (like push to a branch, PR creation, merging, etc).

Github Actions workflow is an automated steps made up of jobs. It is defined in yaml.

# SSH Key

For this to work you need ssh keys. You need to add the public key to the destination server in the path ~/.ssh/authorized_keys.

You need to add the private keys used to ssh to the server to github. Use these steps:

• Go to github repository, click on Settings then Secrets
• Click New repository secret and you’ll be prompted to enter a secret
• Enter the secret name and the contents (of the private ssh key) as requested and click Add Secret. The secret name is used to get the contents later in a Github Actions workflow.
• For the secret name, its always a good practice to use uppercase letters with underscores as spaces like SSH_PRIVATE_KEY.

# Hugo build workflow

# Name of Workflow
name: Hugo build workflow

# Trigger workflow on push or pull request to master
on:
  push:
    branches: [ master ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    # Step 1 - Checks-out your repository under ${GITHUB_WORKSPACE}
    - name: Checkout
      uses: actions/checkout@v2
      with:
          submodules: true  # Fetch Hugo themes
          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod

    # Step 2 - Sets up the latest version of Hugo
    - name: Setup Hugo
      uses: peaceiris/actions-hugo@v2
      with:
          hugo-version: 'latest'

    # Step 3 - Clean and don't fail
    - name: Clean public directory
      run: rm -rf public

    # Step 4 - Builds the site using the latest version of Hugo
    # Also specifies the theme we want to use
    - name: Build the site
      run: hugo -D

    # Adding the Private key
    # We’re supposed to add known_hosts but since we can't get use random
    - name: Install SSH Key
      uses: shimataro/ssh-key-action@v2
      with:
        key: ${{ secrets.SSH_PRIVATE_KEY }}
        known_hosts: 'just-a-placeholder-so-we-dont-get-errors'

    # Rsync public content to remote server
    - name: Deploy with rsync
      run: rsync -avz ./public/ ${{ secrets.SSH_USER }}@${{ secrets.SSH_HOST }}:/var/www/citizix/

The workflow does the following:

This

on:
  push:
    branches: [ master ]

The above comnfigures triggers for the workflow. When code is pushed to master, the workflow is triggered.

The Job section contains the jobs to execute. The above workflow contains one job , the deploy which runs on the latest version of Ubuntu (runs-on: ubuntu-latest). The jobs will execute using steps:

• Step 1: Checks out the code in your repository, including any git submodules
• Step 2: Using an open-source Github action from this person, installs the latest version of Hugo
• Step 3: Removes the public directory if it exists. This could be from previously generated files.
• Step 4: This builds the hugo site. This is specific to Hugo.
• Step 5: This installs the ssh key from the secret added earlier. We can generate the correct known_hosts value with a ssh-keyscan – ssh-keyscan -H IP_ADDRESS_OF_HOST. Once we know this, we can manually add the IP address into the Github Secrets (SSH_HOST) then we can generate the correct info via this:

  steps:
  

• name: Adding Known Hosts run: ssh-keyscan -H ${{ secrets.SSH_HOST }} >> ~/.ssh/known_hosts

  • Step 6: Rsync the public content into Server

# Wrapping up

Here are the steps to summarize everything:

• Generate a SSH Keyphrase using the standard RSA format
• Add the public key to authorized_keys
• Add the private key as a Github secret
• Use Shimataro’s Install SSH Key action to generate a SSH Key in the runner.
• Append the correct known_hosts configuration with ssh-keyscan
• Deploy with Rsync via SSH