From 25f33606a2bcb6e864635e6419dbb448ef168d97 Mon Sep 17 00:00:00 2001
From: Bernhard Kaindl <bernhard.kaindl@cloud.com>
Date: Fri, 24 Jan 2025 12:00:00 +0100
Subject: [PATCH] Hugo docs: When enabled by the fork, preview Hugo docs as its
 gh-pages

Signed-off-by: Bernhard Kaindl <bernhard.kaindl@cloud.com>
---
 .github/workflows/hugo.yml | 79 +++++++++++++++++++++++++++++++++++++-
 1 file changed, 78 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/hugo.yml b/.github/workflows/hugo.yml
index 9b831b12ae7..dc0622d63a0 100644
--- a/.github/workflows/hugo.yml
+++ b/.github/workflows/hugo.yml
@@ -3,11 +3,21 @@ name: Generate and upload Hugo docs
 on:
   push:
     branches: master
+  pull_request:
+    # On pull requests, only run the workflow if Hugo docs are modified
+    paths:
+      - 'doc/**'
+      - '.github/workflows/hugo.yml'
 
 jobs:
-  ocaml:
+  hugo:
     name: Docs
     runs-on: ubuntu-22.04
+    environment:
+      # To be able read var.PREVIEW_HUGO_DOCS, if set in the github-pages environment:
+      name: github-pages
+    outputs:
+      preview: ${{ steps.preview.outputs.done }}  # Set to true if the preview job runs
 
     steps:
       - name: Checkout code
@@ -25,6 +35,9 @@ jobs:
 
       - name: Deploy
         uses: peaceiris/actions-gh-pages@v4
+        # The deploy key used for deployment to https://xenapi-project.github.io
+        # It is stored in the repository's secrets and is used to push the built
+        # documentation. This step skips deployment if it is not set on a clone.
         with:
           deploy_key: ${{ secrets.ACTIONS_DOCS_DEPLOY_KEY }}
           publish_dir: ./doc/public
@@ -35,3 +48,67 @@ jobs:
           destination_dir: new-docs # temporary staging branch
           allow_empty_commit: false
           enable_jekyll: true # do not create .nojekyll file
+
+      # To preview Hugo docs online on GitHub Pages of forks, the steps below are needed.
+      # When not enabled, the preview jobs below are skipped:
+      #
+      # At https://github.com/<user|organisation>/<repo>/settings/pages,
+      # change the deployment source of the fork to "GitHub Pages"
+      #
+      # On https://github.com/<user|organisation>/<repo>/settings/environments/
+      # make sure the environment 'github-pages' exists and in it, at "Deployment branches and tags"
+      # add a wildcard rule that allows deployment from the branches you like to allow
+      # or the rule can be set to "No restriction" to allow deployment from any branch.
+      #
+      # Finally, add a variable named PREVIEW_HUGO_DOCS with the value 'true' to the environment.
+
+      - name: If vars.PREVIEW_HUGO_DOCS is true, enable github pages for the preview
+        if: ${{ vars.PREVIEW_HUGO_DOCS == 'true' }}  # Only runs if set by the admin
+        id: configure-pages
+        with:
+          enablement: true  # Enables GitHub Pages for the clone repository
+        uses: actions/configure-pages@v5  # output: the base_url for the preview site
+
+      - name: If vars.PREVIEW_HUGO_DOCS is true, build the hugo preview
+        if: ${{ vars.PREVIEW_HUGO_DOCS == 'true' }}
+        id: preview
+        env:
+          # Force Hugo to render the site using the baseUrl used by GitHub Pages for the preview:
+          # The default base URL used by GitHub pages of a repository is
+          # https://<user|organisation>.github.io/<repo name>
+          # Owners of forks can setup custom domains for the gh-pages of their repositories instead:
+          # https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site
+          # In this case, the base URL is the custom domain and we read it
+          # from the output of the output variable 'base_url' of the configure-pages action:
+          HUGO_BASEURL: ${{ steps.configure-pages.outputs.base_url }}
+        run: cd doc && hugo --minify && echo done=true >$GITHUB_OUTPUT
+
+      - name: If vars.PREVIEW_HUGO_DOCS is true, upload the Hugo site as an artifact
+        if: ${{ vars.PREVIEW_HUGO_DOCS == 'true' }}
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./doc/public
+
+
+  # When pushed to other repositories, deploy to the repository's GitHub Pages
+  preview-docs:
+    # Add a dependency to the hugo job, skip if the hugo job did not complete
+    needs: hugo
+
+    if: ${{ needs.hugo.outputs.preview == 'true' }}
+
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      id-token: write  # Required for the deployment job to access the uploaded artifact
+      pages: write     # Required for the deployment job to deploy to GitHub Pages
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    runs-on: ubuntu-24.04-arm
+    steps:
+      # If deployed, the summary of this step in the Workflow summary shows the site URL:
+      - name: Deploy uploaded artifact to GitHub Pages for documentation update reviews
+        id: deployment
+        uses: actions/deploy-pages@v4