Render website in PRs

[mattwthompson]

Building locally is helpful, but I can't be too sure of the results of PRs without building on the same hardware with the same pipeline that the website will ultimately be rendered on.

[jameseastwood]

I agree this would be valuable. Do you have an implementation in mind?

[mattwthompson]

The dream is to have something similar to RTD's solution; the engineered stuff on their end so that a checkbox somewhere in their settings has docs auto-magically build on all PRs (i.e. this from an arbitrary PRs) and don't see the light of day otherwise. The developer experience with that feature takes no input and almost immediately lets me preview the website after a PR's changes without them being applied to the live site.

I haven't looked into how to do this with this website, since it's generated with a different pipeline. I think the build process is straightforward and, because it's a static site, it's simply a question of where to host the rendered HTML. From ~2 minutes of searching I'd first try this action before going for a third-party solution: https://github.com/rossjrw/pr-preview-action

[mattwthompson]

@dwhswenson is working on something that could solve this for us

[dwhswenson]

I wouldn't recommend that pr-preview-action since it can't work from forks. The readme claims that it plans to support forks for v2, but that points to a 3-year old PR that mostly discusses that the security issues are significant (they are: that action's approach is to put it in the same pages site that you already have, which means that there's no strict permissions boundary between a PR that you've previewed and your actual public site).

When I went looking in May 2023, here's the action/tool I found: https://github.com/DigitalSVN/GoStatic. That one creates a link that will only live for 3 days and is limited to 100MB. I tried it on my personal site, but my site is way over 100MB, so it failed. But it seemed very easy to use, so if it still lives, it might be worth a try. Concerns about it: there's been no update to their action code in 4 years, the guy who wrote it hasn't done anything at all on GitHub in about 2 years, and there's no clear business plan (the beta is free! and has been for 4 years?) I get the vibe this might be a side business idea that got forgotten. But if it still works, it might meet your needs!

There's also the solution I've been building for my personal site. That is a little less turnkey, but I've been improving it. If the GoStatic action doesn't work, I'll be happy to share what I've been building.

[dwhswenson]

Just a little update here: I went and got a new token set up with GoStatic, and that still seems to run. I'd recommend that for now; mine is designed for you to have full control of it, but requires a bit more work to setup and maintain. Mine is still missing install instructions, but can be found here for the curious (it works on my personal site, which is too large for GoStatic.)

Once you set your GOSTATIC_API_TOKEN secret, here's the workflow I'm using to stage a Hugo site. NB: my build-hugo-site action moves the built site from public to _site to reuse other stuff I'd previously done for my personal Jekyll-based site. So if you have an existing way to build your site, you'll probably need to upload the public directory in the GoStatic action.

# .github/workflows/upload-gostatic.yaml
name: Upload to GoStatic

on:
  pull_request:
    branches:
      - main

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
      contents: read
    steps:
      - uses: actions/checkout@v4
        with:
          submodules: 'recursive'

      - uses: ./.github/actions/build-hugo-site
        with:
          base-url: ""

      - name: Upload to GoStatic
        id: gostatic
        uses: DigitalSVN/GoStatic@v1.0
        with:
          api-token: ${{ secrets.GOSTATIC_API_TOKEN }}
          source-dir: _site

      - name: Comment on PR
        uses: marocchino/sticky-pull-request-comment@v2
        with:
          header: gostatic
          number: ${{ github.event.pull_request.number }}
          message: |
            This PR has been staged at ${{ steps.gostatic.outputs.url }}.
            
            Updated for commit ${{ github.event.pull_request.head.sha }}.

The internal build-hugo-site action:

# .github/actions/build-hugo-site/action.yaml
name: Build Hugo site
description: Build a Hugo site

inputs:
  base-url: 
    description: The base URL for the site
    required: false
    default: ""
  hugo-version:
    description: The version of Hugo to use
    required: false
    default: "0.141.0"

runs:
  using: 'composite'
  steps:
    - name: Install Hugo and Dart SASS
      shell: bash
      env:
        HUGO_VERSION: ${{ inputs.hugo-version }}
      run: |
        wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \
          && sudo dpkg -i ${{ runner.temp }}/hugo.deb
        sudo snap install dart-sass
    - name: Get modules
      shell: bash
      run: |
        hugo mod get -u
    - name: Build the site
      shell: bash
      run: |
        hugo --gc --minify --baseURL="${{ inputs.base-url }}"
    - name: Move the site to the output directory
      shell: bash
      run: |
        mv public _site