refactor(ci): Improve workflow environment detection and reliability

This commit significantly refactors the CI workflows to be more robust, portable, and reliable across different execution environments (GitHub.com, Gitea, and local `act`).

Key changes include:

- **Robust Environment Detection:**
  The primary environment detection logic in the `docs` workflow is overhauled. It no longer relies on a brittle file check. Instead, it now explicitly checks for the `$ACT` environment variable for local `act` runs and the `github.server_url` for Gitea/other self-hosted runners. This provides clearer and more reliable outputs (`is_act`, `is_gitea`, `is_self_hosted`).

- **Smarter Network-Dependent Logic:**
  The decision to use the internal package mirror is no longer tied to the runner type. The `local-setup` action now actively checks for corporate network access by pinging the proxy server and exposes this as an `on-corp-network` output. The dependency installation step now uses this direct, reliable check.

- **Consistent Python Invocation:**
  All calls to `python` have been changed to `python3` to ensure the correct interpreter is used consistently across all environments and to avoid PATH ambiguity.

- **Safer Deployment Trigger:**
  The `deploy` job is now conditionally run based on the `is_self_hosted` output from the `build` job. This ensures that deployments to GitHub Pages are only ever attempted when running on GitHub.com, preventing failures on Gitea and `act`.

Author: SamoraHunter

.github/actions/local-setup/action.yml

@@ -6,21 +6,29 @@ inputs:
   gitea-token:
     description: 'Token for authenticating with Gitea'
     required: false
+outputs:
+  on-corp-network:
+    description: "True if the runner appears to be on the corporate network"
+    value: ${{ steps.proxy-config.outputs.on-corp-network }}
 
 runs:
   using: "composite"
   steps:
     - name: Configure Proxy for Corporate Network
+      id: proxy-config
       shell: bash
       run: |
+        ON_CORP=false
         if ping -c 1 dh-cap02 &> /dev/null; then
           echo "✅ Proxy server 'dh-cap02' is available. Configuring environment variables."
           echo "http_proxy=http://dh-cap02:8008" >> $GITHUB_ENV
           echo "https_proxy=http://dh-cap02:8008" >> $GITHUB_ENV
+          ON_CORP=true
 
           NO_PROXY_LIST="localhost,127.0.0.1,kch-cap.kingsch.nhs.uk,github.com,*.blob.core.windows.net,${ACTIONS_CACHE_URL#http://}"
           echo "NO_PROXY=$NO_PROXY_LIST" >> $GITHUB_ENV
         fi
+        echo "on-corp-network=${ON_CORP}" >> $GITHUB_OUTPUT
 
     - name: Install System Dependencies
       shell: bash

.github/workflows/docs.yml

@@ -19,6 +19,8 @@ concurrency:
 jobs:
   build:
     runs-on: ubuntu-latest
+    outputs:
+      is_self_hosted: ${{ steps.detect_env.outputs.is_self_hosted }}
     env:
       DEBIAN_FRONTEND: noninteractive
     steps:
@@ -28,29 +30,39 @@ jobs:
       - name: Detect Runner Environment
         id: detect_env
         run: |
-          if [ -f "/usr/local/share/ca-certificates/kch_certauth.crt" ]; then
-            echo "is_act_runner=true" >> $GITHUB_OUTPUT
+          IS_SELF_HOSTED=false
+          IS_ACT=false
+          IS_GITEA=false
+          if [ -n "$ACT" ]; then
+            echo "Runner environment: local act"
+            IS_ACT=true
+            IS_SELF_HOSTED=true
+          elif [ "${{ github.server_url }}" != "https://github.com" ]; then
+            echo "Runner environment: Gitea"
+            IS_GITEA=true
+            IS_SELF_HOSTED=true
+          else
+            echo "Runner environment: GitHub.com"
           fi
+          echo "is_act=$IS_ACT" >> $GITHUB_OUTPUT
+          echo "is_gitea=$IS_GITEA" >> $GITHUB_OUTPUT
+          echo "is_self_hosted=$IS_SELF_HOSTED" >> $GITHUB_OUTPUT
 
       - name: Perform Local Runner Setup
         id: local_setup
-        if: steps.detect_env.outputs.is_act_runner == 'true'
+        if: steps.detect_env.outputs.is_self_hosted == 'true'
         uses: ./.github/actions/local-setup
         with:
           gitea-token: ${{ secrets.GITEA_TOKEN }}
 
       - name: Set up Python
         uses: actions/setup-python@v5
-        env:
-          http_proxy: ${{ env.http_proxy }}
-          https_proxy: ${{ env.https_proxy }}
-          AGENT_TOOLSDIRECTORY: /opt/hostedtoolcache
         with:
           python-version: '3.10.18'
           check-latest: false
 
       - name: Fix pip installation
-        if: steps.detect_env.outputs.is_act_runner == 'true'
+        if: steps.detect_env.outputs.is_self_hosted == 'true'
         run: |
           curl -sS https://bootstrap.pypa.io/get-pip.py | python3 - --ignore-installed
           python3 -m pip install --upgrade --ignore-installed pip setuptools wheel
@@ -60,25 +72,25 @@ jobs:
           GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
         run: |
           pip_install_args=()
-          if [[ "${{ steps.detect_env.outputs.is_act_runner }}" == "true" ]] && [[ -n "${GITEA_TOKEN}" ]]; then
-              echo "🔧 Running in act - using local mirror and removing hash requirements"
+          if [[ "${{ steps.local_setup.outputs.on-corp-network }}" == "true" ]]; then
+              echo "🔧 On corporate network - using local mirror and removing hash requirements"
               find . -name "requirements*.txt" -type f -exec sed -i 's/ --hash=sha256:[a-f0-9]*//g' {} \;
               pip_install_args+=("--trusted-host" "dh-cap02" "-i" "http://dh-cap02:8008/mirrors/pat2vec")
           fi
 
           echo "Installing project dependencies for docs..."
-          python -m pip install "${pip_install_args[@]}" -e ".[dev]"
+          python3 -m pip install "${pip_install_args[@]}" -e ".[dev]"
 
       - name: Build Sphinx documentation
         run: |
-          python -m sphinx.cmd.build -b html docs/source docs/build/html
+          python3 -m sphinx.cmd.build -b html docs/source docs/build/html
 
       - name: Setup Pages
-        if: steps.detect_env.outputs.is_act_runner != 'true'
+        if: steps.detect_env.outputs.is_self_hosted != 'true'
         uses: actions/configure-pages@v4
 
       - name: Upload artifact
-        if: steps.detect_env.outputs.is_act_runner != 'true'
+        if: steps.detect_env.outputs.is_self_hosted != 'true'
         uses: actions/upload-pages-artifact@v3
         with:
           path: docs/build/html
@@ -89,7 +101,7 @@ jobs:
       url: ${{ steps.deployment.outputs.page_url }}
     runs-on: ubuntu-latest
     needs: build
-    if: github.server_url == 'https://github.com'
+    if: needs.build.outputs.is_self_hosted != 'true'
     steps:
       - name: Deploy to GitHub Pages
         id: deployment