docs: allow publishing docs from forked PRs

.github/actions/deploy-versioned-pages/action.yml

@@ -1,5 +1,5 @@
 # *******************************************************************************
-# Copyright (c) 2024 Contributors to the Eclipse Foundation
+# Copyright (c) 2025 Contributors to the Eclipse Foundation
 #
 # See the NOTICE file(s) distributed with this work for additional
 # information regarding copyright ownership.
@@ -41,33 +41,37 @@ runs:
       id: calc
       shell: bash
       run: |
-        if [[ ${{github.event_name}} == 'pull_request' ]]; then
-          echo "target_folder=pr-${{github.event.pull_request.number}}" >> $GITHUB_OUTPUT
-        elif [[ ${{github.ref_name}} != 'main' ]]; then
-          echo "target_folder=${{github.ref_name}}" >> $GITHUB_OUTPUT
+        if [[ "${{ github.event_name }}" == 'pull_request_target' || "${{ github.event_name }}" == 'pull_request' ]]; then
+          target_folder="pr-${{ github.event.pull_request.number }}"
         else
-          echo "target_folder=/" >> $GITHUB_OUTPUT
+          target_folder="${{github.ref_name}}"
         fi
-    - name: Prepare
+        echo "target_folder=$target_folder" >> $GITHUB_OUTPUT
+
+    - name: Prepare the deploy folder
       shell: bash
       run: |
         # Prepare the deploy folder
-        mkdir -p deploy_root/${{ steps.calc.outputs.target_folder }}
+        mkdir -p deploy_root
+        mkdir -p version_root
         # Move the files to the deploy folder
-        mv ${{ inputs.source_folder }}/* deploy_root/${{ steps.calc.outputs.target_folder }}
+        mv ${{ inputs.source_folder }}/* deploy_root/
         # Ensure that the folder is not treated as a Jekyll site
         touch deploy_root/.nojekyll
 
         # Add the target folder to the versions file
-        git fetch origin gh-pages --depth 1
-        git checkout origin/gh-pages -- "${{ inputs.versions_file }}"
+        BASE_REPO="https://github.com/${{ github.repository }}.git"
+
+        echo "Fetching gh-pages from BASE_REPO: $BASE_REPO"
+        git remote add base "$BASE_REPO" || git remote set-url base "$BASE_REPO"
+        git fetch base gh-pages --depth 1
+
+        # Checkout only the versions file from gh-pages branch of the base repo
+        git checkout base/gh-pages -- "${{ inputs.versions_file }}"
 
         target="${{ steps.calc.outputs.target_folder }}"
-        if [ "$target" = "/" ]; then
-          new_version="stable"
-        else
-          new_version="$target"
-        fi
+        new_version="${{ steps.calc.outputs.target_folder }}"
+
 
         if jq -e --arg version "$new_version" 'map(select(.version == $version)) | length > 0' "${{ inputs.versions_file }}" > /dev/null; then
           echo "Version '$new_version' already exists in ${{ inputs.versions_file }}"
@@ -84,16 +88,29 @@ runs:
           jq --arg version "$new_version" --arg url "$new_url" '. + [{"version": $version, "url": $url}]' "${{ inputs.versions_file }}" > tmp_versions.json
           mv tmp_versions.json "${{ inputs.versions_file }}"
         fi
-        mv "${{ inputs.versions_file }}" deploy_root/
+        mv "${{ inputs.versions_file }}" version_root/
         ls -al .
         ls -al deploy_root
-    - name: Deploy 🚀
+        ls -al version_root
+        cat  version_root/"${{ inputs.versions_file }}"
+
+    - name: Deploy Documentation
       uses: JamesIves/github-pages-deploy-action@v4
       with:
         folder: deploy_root
+        target-folder: ${{ steps.calc.outputs.target_folder }}
+        clean: true
+        clean-exclude: .nojekyll
+
+    - name: Deploy  version file 🚀
+      uses: JamesIves/github-pages-deploy-action@v4
+      with:
+        folder: version_root
         clean: false
+
+
     - name: Comment on PR with docs URL
-      if: ${{ github.event_name == 'pull_request' && inputs.create_comment == 'true' }}
+      if: ${{ github.event_name == 'pull_request_target' && inputs.create_comment == 'true' }}
       uses: peter-evans/create-or-update-comment@v4
       with:
         issue-number: ${{github.event.pull_request.number}}

.github/workflows/docs-cleanup.yml

@@ -1,5 +1,5 @@
 # *******************************************************************************
-# Copyright (c) 2024 Contributors to the Eclipse Foundation
+# Copyright (c) 2025 Contributors to the Eclipse Foundation
 #
 # See the NOTICE file(s) distributed with this work for additional
 # information regarding copyright ownership.
@@ -13,7 +13,7 @@
 
 name: Cleanup Documentation
 on:
-  pull_request:
+  pull_request_target:
     types: [closed]
   delete:
 jobs:
@@ -28,7 +28,9 @@ jobs:
     steps:
       - uses: actions/checkout@v4
         with:
+          repository: ${{ github.event.pull_request.base.repo.full_name }} # Ensures we checkout the base repo, not the fork
           ref: gh-pages
+          fetch-depth: 0
       - name: Remove version
         run: |
           if [[ ${{ github.event_name }} == "pull_request" ]]; then

.github/workflows/docs.yml

@@ -1,5 +1,5 @@
 # *******************************************************************************
-# Copyright (c) 2024 Contributors to the Eclipse Foundation
+# Copyright (c) 2025 Contributors to the Eclipse Foundation
 #
 # See the NOTICE file(s) distributed with this work for additional
 # information regarding copyright ownership.
@@ -13,32 +13,64 @@
 
 name: Documentation
 on:
-  pull_request:
-    types: [opened, reopened, synchronize]
+  pull_request_target:
+    types: [opened, reopened, synchronize] # Handles forked PRs
   push:
   merge_group:
     types: [checks_requested]
+
 jobs:
   docs-build:
     name: Build documentation
     runs-on: ubuntu-latest
     permissions:
       pull-requests: write
     steps:
-      - name: Checkout repository
+      # ------------------------------------------------------------------------------
+      # Checkout the correct branch safely in all scenarios (PRs, forks, merges)
+      # ------------------------------------------------------------------------------
+      # | Condition                              | Event Type         | Checked Out Branch    |
+      # |----------------------------------------|--------------------|-----------------------|
+      # | github.head_ref                        | pull_request_target | PR branch (source branch) |
+      # | github.event.pull_request.head.ref     | pull_request        | PR branch (source branch) |
+      # | github.ref                             | push, merge_group   | The branch being pushed/merged |
+      # ------------------------------------------------------------------------------
+      # ------------------------------------------------------------------------------
+      # Checkout the correct repository safely in all scenarios (PRs, forks, merges)
+      # ------------------------------------------------------------------------------
+      # | Condition                                      | Event Type         | Checked Out Repository           |
+      # |------------------------------------------------|--------------------|----------------------------------|
+      # | github.event.pull_request.head.repo.full_name  | pull_request       | Forked repository (if PR is from a fork) |
+      # | github.repository                              | push, merge_group  | Default repository (same repo PRs, merges, pushes) |
+      - name: Checkout repository (Handle all events)
         uses: actions/checkout@v4.2.2
+        with:
+          ref: ${{ github.head_ref || github.event.pull_request.head.ref || github.ref }}
+          repository: ${{ github.event.pull_request.head.repo.full_name || github.repository }}
+      - name: Ensure GitHub Token is Masked
+        run: echo "::add-mask::$GITHUB_TOKEN"
       - name: Setup Bazel
         uses: bazel-contrib/setup-bazel@0.9.1
       - name: Build documentation
         run: |
           bazel build //docs:github-pages && cp bazel-bin/docs/github-pages.tar .
+        # ------------------------------------------------------------------------------
+        # Generate a unique artifact name to ensure proper tracking in all scenarios
+        # ------------------------------------------------------------------------------
+        # | Condition                                     | Event Type             | Artifact Name Value                          |
+        # |-----------------------------------------------|------------------------|----------------------------------------------|
+        # | github.event.pull_request.head.sha            | pull_request           | PR commit SHA (ensures uniqueness per PR)    |
+        # | github.event.pull_request.head.sha            | pull_request_target    | PR commit SHA (ensures uniqueness per PR)    |
+        # | github.sha                                    | push, merge_group      | Current commit SHA (used for main branch)    |
+        # ------------------------------------------------------------------------------
       - name: Upload artifact for job analysis
         uses: actions/upload-artifact@v4.4.0
         with:
-          name: github-pages-${{ github.sha }}
+          name: github-pages-${{ github.event.pull_request.head.sha || github.sha }}
           path: github-pages.tar
           retention-days: 1
           if-no-files-found: error
+
   docs-deploy:
     name: Deploy documentation to GitHub Pages
     permissions:
@@ -52,26 +84,35 @@ jobs:
     runs-on: ubuntu-latest
     needs: docs-build
     steps:
-      # Checkout is required to get the local actions.
+      # ------------------------------------------------------------------------------
+      # Always checks out the BASE repository since pull_request_target is used.
+      # This ensures that the workflow runs with trusted code from the base repo,
+      # even when triggered by a pull request from a fork.
+      # ------------------------------------------------------------------------------
       - name: Checkout repository
         uses: actions/checkout@v4.2.2
+
       - name: Download documentation artifact
         uses: actions/download-artifact@v4.1.8
+        # ------------------------------------------------------------------------------
+        # Generate a unique artifact name to ensure proper tracking in all scenarios
+        # ------------------------------------------------------------------------------
+        # | Condition                                     | Event Type             | Artifact Name Value                          |
+        # |-----------------------------------------------|------------------------|----------------------------------------------|
+        # | github.event.pull_request.head.sha            | pull_request           | PR commit SHA (ensures uniqueness per PR)    |
+        # | github.event.pull_request.head.sha            | pull_request_target    | PR commit SHA (ensures uniqueness per PR)    |
+        # | github.sha                                    | push, merge_group      | Current commit SHA (used for main branch)    |
+        # ------------------------------------------------------------------------------
         with:
-          name: github-pages-${{ github.sha }}
+          name: github-pages-${{ github.event.pull_request.head.sha || github.sha }}
+
       - name: Untar documentation artifact
         run: mkdir -p extracted_docs && tar -xf github-pages.tar -C extracted_docs
+
       - name: Deploy 🚀
         id: pages-deployment
         continue-on-error: true
         uses: ./.github/actions/deploy-versioned-pages
         with:
           source_folder: extracted_docs
-      - name: Deploy (fallback) 🚀
-        id: deployment
-        # If the new deployment from gh-pages branch fails, at least deploy the current version.
-        # This is only a short-term solution, until we can change the repository settings.
-        if: ${{ steps.pages-deployment.outcome == 'failure' && github.event_name == 'push' && github.ref_name == 'main' }}
-        uses: actions/deploy-pages@v4.0.5
-        with:
-          artifact_name: github-pages-${{ github.sha }}
+