PR Preview GitHub Action [skip ci]

.env.example

@@ -1,4 +1,4 @@
-BUILD_MODE=local # local / demo / production
+BUILD_MODE=local # local / pr-preview / production
 
 LOCAL_ENABLE_REDIRECTS=Yes
 LOCAL_ENABLE_TAGS=Yes

.github/workflows/deploy-pr-preview.yaml

@@ -0,0 +1,105 @@
+name: Deploy to PR Preview
+
+on:
+  pull_request:
+    branches:
+      - main
+
+env:
+  PR_PREVIEW_PULL_REQUEST_NUMBER: ${{github.event.pull_request.number}}
+  PR_PREVIEW_SUBDOMAIN: pr-${{github.event.pull_request.number}}-preview
+  PR_PREVIEW_DEPLOY_LOG_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+  PR_PREVIEW_BUCKET: s3://khpreview.dea.ga.gov.au
+
+permissions:
+  id-token: write # For requesting the JWT used by OIDC Authentication
+  issues: write
+  pull-requests: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        python-version: ["3.11"]
+        node-version: [18.x]
+
+    steps:
+      - name: Find Comment
+        uses: peter-evans/find-comment@v3
+        id: find-comment
+        with:
+          issue-number: ${{ github.event.pull_request.number }}
+          comment-author: 'github-actions[bot]'
+          body-includes: PR Preview
+
+      - name: "Comment: PR Preview is deploying"
+        uses: peter-evans/create-or-update-comment@v4
+        with:
+          issue-number: ${{github.event.pull_request.number}}
+          comment-id: ${{ steps.find-comment.outputs.comment-id }}
+          edit-mode: replace
+          body: |
+            ## :hourglass: PR Preview is deploying ...
+
+            <table>
+                <tr>
+                    <td><strong>Deploy log:</strong></td>
+                    <td><a href="${{ env.PR_PREVIEW_DEPLOY_LOG_URL }}">View the log</a></td>
+                </tr>
+            </table>
+
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          submodules: true
+
+      - name: Pull latest from submodules
+        run: git submodule foreach git pull origin stable
+          # This doesn't update the submodule to the latest commit on the origin; therefore, you should manually do this on a semi-regular basis.
+
+      - name: Install Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: 'pip'  # Use pip to cache the installed dependencies
+
+      - name: Install dependencies
+        run: ./install-dependencies.sh
+
+      - name: Build site
+        env:
+          BUILD_MODE: pr-preview
+        run: ./build-pr-preview.sh
+
+      - name: Configure AWS credentials via OIDC
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          role-to-assume: arn:aws:iam::538673716275:role/github-actions-dea-knowledge-hub-prs
+          aws-region: ap-southeast-2
+
+      - name: Deploy preview site
+        run: |
+          aws s3 sync --delete output "$PR_PREVIEW_BUCKET/$PR_PREVIEW_SUBDOMAIN"
+
+      - name: "Update Comment: PR Preview is ready"
+        uses: peter-evans/create-or-update-comment@v4
+        with:
+          issue-number: ${{github.event.pull_request.number}}
+          comment-id: ${{ steps.find-comment.outputs.comment-id }}
+          edit-mode: replace
+          body: |
+            ## :star2: PR Preview is ready!
+
+            <table>
+                <tr>
+                    <td><strong>Preview site:</strong></td>
+                    <td><a href="https://${{ env.PR_PREVIEW_SUBDOMAIN }}.khpreview.dea.ga.gov.au/">${{ env.PR_PREVIEW_SUBDOMAIN }}.khpreview.dea.ga.gov.au</a></td>
+                </tr>
+                <tr>
+                    <td><strong>Deploy log:</strong></td>
+                    <td><a href="${{ env.PR_PREVIEW_DEPLOY_LOG_URL }}">View the log</a></td>
+                </tr>
+            </table>
+

.github/workflows/deploy-production.yaml

@@ -12,12 +12,13 @@ permissions:
 
 jobs:
   publish:
-    name: Publish
     runs-on: ubuntu-latest
+
     strategy:
       matrix:
         python-version: ["3.11"]
         node-version: [18.x]
+
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
@@ -33,8 +34,8 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
 
-      - name: Install requirements
-        run: ./install-production.sh
+      - name: Install dependencies
+        run: ./install-dependencies.sh
 
       - name: Build site
         env:

build-demo.sh → build-pr-preview.sh

@@ -1,10 +1,6 @@
 #!/bin/bash
 
-python -m pip install -r ./docs/requirements.txt
-
-npm install -g sass
-
-apt-get install -y pandoc
+set -eox pipefail
 
 mkdir -p ./output
 

docs/_modules/pr_preview.py

@@ -0,0 +1,11 @@
+import os
+
+def banner():
+    pull_request_number = os.environ.get("PR_PREVIEW_PULL_REQUEST_NUMBER")
+    deploy_log_url = os.environ.get("PR_PREVIEW_DEPLOY_LOG_URL")
+
+    knowledge_hub_url = "https://knowledge.dea.ga.gov.au/"
+    github_url = "https://github.com/GeoscienceAustralia/dea-knowledge-hub"
+
+    return f'You are viewing <strong>PR Preview #{pull_request_number}</strong>, not the official <a href="{knowledge_hub_url}">DEA Knowledge Hub</a>. View the <a href="{github_url}/pull/{pull_request_number}">Pull request</a> or <a href="{deploy_log_url}">Deploy log</a>.'
+

docs/_modules/utilities.py

@@ -10,7 +10,7 @@ def current_year():
 def optional_exclude_pattern(environment_variable, exclude_pattern):
     if (
         os.environ.get(environment_variable) == "No"
-        and not os.environ.get("BUILD_MODE") in ["demo", "production"]
+        and not os.environ.get("BUILD_MODE") in ["pr-preview", "production"]
     ):
         return [exclude_pattern]
     else:

docs/conf.py

@@ -4,13 +4,14 @@
 sys.path.insert(0, os.path.abspath('.'))
 from _modules import utilities
 from _modules import mock_imports
-from _modules import deploy_banner
+from _modules import pr_preview
 
 environment = {
     "build_mode": os.environ.get("BUILD_MODE"),
     "git_branch": os.environ.get("BRANCH"),
     "local_enable_redirects": os.environ.get("LOCAL_ENABLE_REDIRECTS"),
     "local_enable_tags": os.environ.get("LOCAL_ENABLE_TAGS"),
+    "pr_preview_subdomain": os.environ.get("PR_PREVIEW_SUBDOMAIN"),
 }
 
 project = "DEA Knowledge Hub"
@@ -49,7 +50,7 @@
 language = "en"
 
 if environment["build_mode"] == "production": html_baseurl = "https://knowledge.dea.ga.gov.au/"
-elif environment["build_mode"] == "demo": html_baseurl = f"https://{environment['git_branch']}--dea-docs.netlify.app/"
+elif environment["build_mode"] == "pr-preview": html_baseurl = f"https://{environment['pr_preview_subdomain']}.khpreview.dea.ga.gov.au/"
 else: html_baseurl = ""
 
 html_permalinks = False
@@ -87,7 +88,7 @@
 external_toc_path = "table_of_contents.yaml"
 
 if (
-    environment["build_mode"] in ["demo", "production"]
+    environment["build_mode"] in ["pr-preview", "production"]
     or environment["local_enable_redirects"] == "Yes"
 ): rediraffe_redirects = utilities.source_redirects("_redirects/*.txt")
 
@@ -112,7 +113,7 @@
 notfound_urls_prefix = ""
 
 tags_create_tags = (
-    environment["build_mode"] in ["demo", "production"]
+    environment["build_mode"] in ["pr-preview", "production"]
     or environment["local_enable_tags"] == "Yes"
 )
 
@@ -141,8 +142,8 @@
     },
 }
 
-if environment["build_mode"] == "demo":
-    html_theme_options["announcement"] = deploy_banner.banner()
+if environment["build_mode"] == "pr-preview":
+    html_theme_options["announcement"] = pr_preview.banner()
 
 html_context = {
     "default_mode": "light",
@@ -155,4 +156,3 @@
 suppress_warnings = [
     # "etoc.toctree"
 ]
-