From 97c051621a8afe83fc569bcb3dd666262bd18f4c Mon Sep 17 00:00:00 2001 From: Dan Calavrezo Date: Mon, 10 Feb 2025 17:54:33 +0200 Subject: [PATCH 1/6] docs: allow publishing docs from forked PRs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fixes issues with race conditions by enabling folder cleaning Requires maintainer approval via an environment. Adapt workflows to correctly handle pull_request_target by explicitly checking out the correct repository. Flattened folder structure gh-pages/ ................. │─ pr-42/ # PR #42 preview │─ pr-99/ # PR #99 preview │─ feature-x/ # Feature branch preview │─ v17/ # Tagged release │─ main/ # main branch (alternatively "latest") In addition to this repo, there are a couple more changes that are needed: - the otterdog repo has to be updated and add the proper maintainers to the github-pages env - the eclipse-score.github.io repo has to be updated so that the Docs refrences the /main folder by default closes #168 #194 #269 Signed-off-by: Dan Calavrezo --- .../actions/deploy-versioned-pages/action.yml | 55 ++++++++++++------- .github/workflows/docs-cleanup.yml | 7 ++- .github/workflows/docs.yml | 36 ++++++++---- 3 files changed, 66 insertions(+), 32 deletions(-) diff --git a/.github/actions/deploy-versioned-pages/action.yml b/.github/actions/deploy-versioned-pages/action.yml index a02efec6817..a7c10d50d27 100644 --- a/.github/actions/deploy-versioned-pages/action.yml +++ b/.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="$target" + 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}} diff --git a/.github/workflows/docs-cleanup.yml b/.github/workflows/docs-cleanup.yml index 8b2dc8c2111..39ea4ed9634 100644 --- a/.github/workflows/docs-cleanup.yml +++ b/.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,10 @@ 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 + token: ${{ secrets.GITHUB_TOKEN }} - name: Remove version run: | if [[ ${{ github.event_name }} == "pull_request" ]]; then diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 0807dd2d348..e0b3ce166fb 100644 --- a/.github/workflows/docs.yml +++ b/.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,11 +13,12 @@ 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 @@ -25,20 +26,27 @@ jobs: permissions: pull-requests: write steps: - - name: Checkout repository + - 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: 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 . + - 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: @@ -51,27 +59,33 @@ jobs: cancel-in-progress: false runs-on: ubuntu-latest needs: docs-build + environment: github-pages # Requires approval before execution steps: - # Checkout is required to get the local actions. - - name: Checkout repository + - name: Checkout repository (Handle both PR 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: Download documentation artifact uses: actions/download-artifact@v4.1.8 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 }} + artifact_name: github-pages-${{ github.event.pull_request.head.sha || github.sha }} + From 49ffae9289e758beebc502c2f0f4804dd14ac714 Mon Sep 17 00:00:00 2001 From: Dan Calavrezo Date: Mon, 10 Feb 2025 18:05:55 +0200 Subject: [PATCH 2/6] docs: fixed yamlfmt issues Signed-off-by: Dan Calavrezo --- .github/workflows/docs.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index e0b3ce166fb..40c9fcbe24b 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -14,7 +14,7 @@ name: Documentation on: pull_request_target: - types: [opened, reopened, synchronize] # Handles forked PRs + types: [opened, reopened, synchronize] # Handles forked PRs push: merge_group: types: [checks_requested] @@ -59,7 +59,7 @@ jobs: cancel-in-progress: false runs-on: ubuntu-latest needs: docs-build - environment: github-pages # Requires approval before execution + environment: github-pages # Requires approval before execution steps: - name: Checkout repository (Handle both PR events) uses: actions/checkout@v4.2.2 From d12ddf3907cf43e0e1af8901683f908940ab88ba Mon Sep 17 00:00:00 2001 From: Dan Calavrezo Date: Tue, 11 Feb 2025 13:17:42 +0200 Subject: [PATCH 3/6] docs: addressed PR comments Addressed PR comments. - use base action when performing deployment - added extra comments Signed-off-by: Dan Calavrezo --- .../actions/deploy-versioned-pages/action.yml | 2 +- .github/workflows/docs.yml | 49 ++++++++++++++----- 2 files changed, 37 insertions(+), 14 deletions(-) diff --git a/.github/actions/deploy-versioned-pages/action.yml b/.github/actions/deploy-versioned-pages/action.yml index a7c10d50d27..c8577e2aa88 100644 --- a/.github/actions/deploy-versioned-pages/action.yml +++ b/.github/actions/deploy-versioned-pages/action.yml @@ -70,7 +70,7 @@ runs: git checkout base/gh-pages -- "${{ inputs.versions_file }}" target="${{ steps.calc.outputs.target_folder }}" - new_version="$target" + 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 diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 40c9fcbe24b..a05cf30801a 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -26,19 +26,43 @@ jobs: permissions: pull-requests: write steps: + # ------------------------------------------------------------------------------ + # 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: @@ -63,12 +87,18 @@ jobs: steps: - name: Checkout repository (Handle both PR 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: 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.event.pull_request.head.sha || github.sha }} @@ -82,10 +112,3 @@ jobs: with: source_folder: extracted_docs - - name: Deploy (fallback) 🚀 - id: deployment - 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.event.pull_request.head.sha || github.sha }} - From 73e4382f9ced6de81db73ed22ea8c710c6784f5e Mon Sep 17 00:00:00 2001 From: Dan Calavrezo Date: Tue, 11 Feb 2025 13:22:18 +0200 Subject: [PATCH 4/6] docs: removed superfluous token param Signed-off-by: Dan Calavrezo --- .github/workflows/docs-cleanup.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/workflows/docs-cleanup.yml b/.github/workflows/docs-cleanup.yml index 39ea4ed9634..99714959c0c 100644 --- a/.github/workflows/docs-cleanup.yml +++ b/.github/workflows/docs-cleanup.yml @@ -31,7 +31,6 @@ jobs: repository: ${{ github.event.pull_request.base.repo.full_name }} # Ensures we checkout the base repo, not the fork ref: gh-pages fetch-depth: 0 - token: ${{ secrets.GITHUB_TOKEN }} - name: Remove version run: | if [[ ${{ github.event_name }} == "pull_request" ]]; then From c931e2f4f56764ee86c971937fa78570a2c3eff6 Mon Sep 17 00:00:00 2001 From: Dan Calavrezo Date: Tue, 11 Feb 2025 14:57:38 +0200 Subject: [PATCH 5/6] docs: added extra comment after PR review Signed-off-by: Dan Calavrezo --- .github/workflows/docs.yml | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index a05cf30801a..db4b0863d1a 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -57,8 +57,8 @@ jobs: # ------------------------------------------------------------------------------ # Generate a unique artifact name to ensure proper tracking in all scenarios # ------------------------------------------------------------------------------ - # | Condition | Event Type | Artifact Name Value | - # |------------------------------------------------|------------------------|-----------------------------------------------| + # | 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) | @@ -85,7 +85,12 @@ jobs: needs: docs-build environment: github-pages # Requires approval before execution steps: - - name: Checkout repository (Handle both PR events) + # ------------------------------------------------------------------------------ + # 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 @@ -93,8 +98,8 @@ jobs: # ------------------------------------------------------------------------------ # Generate a unique artifact name to ensure proper tracking in all scenarios # ------------------------------------------------------------------------------ - # | Condition | Event Type | Artifact Name Value | - # |------------------------------------------------|------------------------|-----------------------------------------------| + # | 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) | From 5e5a1ed7e353af909f4f10c8441cf7014dd36b51 Mon Sep 17 00:00:00 2001 From: Dan Calavrezo Date: Tue, 11 Feb 2025 17:35:13 +0200 Subject: [PATCH 6/6] docs: remove workflow check Since we execute the action from the base repo, we don't need maintainers to trigger the workflow executions. Signed-off-by: Dan Calavrezo --- .github/workflows/docs.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index db4b0863d1a..e1174f05908 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -83,7 +83,6 @@ jobs: cancel-in-progress: false runs-on: ubuntu-latest needs: docs-build - environment: github-pages # Requires approval before execution steps: # ------------------------------------------------------------------------------ # Always checks out the BASE repository since pull_request_target is used.