_Publishing via GitHub actions - roman-gardens/gre GitHub Wiki

Before publishing updates to the public website, it is a good idea to publish to a test website to review for any inadvertent problems. (In theory, the website published by GitHub should look exactly the same as the website previewed locally via Hugo, but in practice, theory does not always match reality.)

The GRE project has a few different publishing options that we've set up as GitHub actions:

publish to roman-gardens.github.io -- this is the public website!
publish to test-a -- used for testing article updates
publish to test-b -- used for testing new features
publish to test-drafts -- this will include all articles, including drafts

Each of these publishing destinations is a separate GitHub repo that holds the website content that Hugo generates from the source markdown documents. Each of these repos has been configured to use GitHub Pages, which is used to host the website.

Publishing to the "test-a" website

Supposed we have some changes already committed to the main branch of the "gre" repo that we would like to preview on a test website.

Go to the source repo https://github.com/roman-gardens/gre
Go to the "Actions" tab
On the left, click the workflow called "publish to test-a"
On the right, click the "Run workflow" button and select the branch you would like to use (if you are not using a special branch, then select "main")

It may take a minute for the process to run. The page will automatically update when the process is complete. After it finishes, the "test-a" repo may take another minute for GitHub to build the actual website from the website files. So the entire process may take a couple minutes.

Check the new test website at https://roman-gardens.github.io/test-a/ and be sure to do a hard-reload in your browser (CTRL-SHIFT-R) to force it to fetch all the latest files so you can verify any changes.

If you are happy with the test website, and are ready to update the public website, then run the "publish to roman-gardens.github.io" workflow.

How was this set up?

The GitHub actions and website repositories have already been set up, but the documentation below explains how the this was done.

Note that the following steps require admin rights to the organization and repository. (Alternatively, an individual user could follow these same steps to set up their own test website under their user account.)

Create the test repo

Create a new repo for the organization and set up github pages:

Go to the main org page https://github.com/roman-gardens/
Click "New" to create a new repo
Name it something like test-a
Make it public
Add a README file
Click the "Create repository" button

Create the test website

From the new repo, click "Settings" > "Pages" tab (on the left, near the bottom)
Source = Deploy from a branch
Under "Branch", change "None" to the "main" branch
Click "Save"

The site URL will be something like https://roman-gardens.github.io/test-a/
Go ahead and test it out in your browser. If it doesn't appear right away, wait a few moments and reload the page. Once it is ready, the site will initially just have the name of the repo ("test-a").

Set up deployment keys

We need to set up deployment keys so that the test site has permissions to be deployed from the main repo.

From a command line, you can generate a pair of keys with the following command:

ssh-keygen -t rsa -b 4096 -C "roman-gardens" -f mykeys -N ""

You should now have 2 new files in your current directory:

mykeys (private key)
mykeys.pub (public key)

Add the private key to the source repo:

Go to the source repo https://github.com/roman-gardens/gre
Settings > Secrets and variables > Actions > "New repository secret"
Set the name to something like ACTIONS_DEPLOY_KEY_TEST_A
Set the value to the entire contents of the mykeys file
Click the "Add secret" button

Add the public key to the test repo:

Go to the new test repo https://github.com/roman-gardens/test-a
Settings > Deploy Keys > Add deploy key
Set the title to something like ACTIONS_DEPLOY_KEY_TEST_A
Set the key to the entire contents of the mykeys.pub file
Check the box to "Allow write access"
Click the "Add key" button

Create a GitHub action

Next we'll create a GitHub action that can be used to deploy the test website:

Go back to the source repo https://github.com/roman-gardens/gre
Add a new file called something like .github/workflows/publish-test-a.yml that contains the following code, making sure to replace the 4 occurrences of "test-a" and "TEST_A" with whatever you called your new repo:

name: publish to test-a

on:
  workflow_dispatch:
    branches:
      - main  # User can select branch to deploy when running the action

jobs:
  build-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          submodules: false
          fetch-depth: 0

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v3
        with:
          hugo-version: '0.145.0'
          # extended: true

      - name: Build
        run: hugo --minify --baseURL "https://roman-gardens.github.io/test-a/"

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v4
        with:
          deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY_TEST_A }}
          external_repository: roman-gardens/test-a
          publish_branch: main
          publish_dir: ./docs
          commit_message: ${{ github.event.head_commit.message }}

These steps have already been done for test-a, but they could be used again to create a secondary test site test-b, etc.