Skip to content

Commit a8e9df9

Browse files
dcalavrezo-qorixdcalavrezo-qorix
authored
docs: allow publishing docs from forked PRs (#327)
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 Signed-off-by: Dan Calavrezo <dan.calavrezo.ext@qorix.ai>
1 parent 62b44b5 commit a8e9df9

File tree

3 files changed

+96
-36
lines changed

3 files changed

+96
-36
lines changed

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

Lines changed: 36 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
# *******************************************************************************
2-
# Copyright (c) 2024 Contributors to the Eclipse Foundation
2+
# Copyright (c) 2025 Contributors to the Eclipse Foundation
33
#
44
# See the NOTICE file(s) distributed with this work for additional
55
# information regarding copyright ownership.
@@ -41,33 +41,37 @@ runs:
4141
id: calc
4242
shell: bash
4343
run: |
44-
if [[ ${{github.event_name}} == 'pull_request' ]]; then
45-
echo "target_folder=pr-${{github.event.pull_request.number}}" >> $GITHUB_OUTPUT
46-
elif [[ ${{github.ref_name}} != 'main' ]]; then
47-
echo "target_folder=${{github.ref_name}}" >> $GITHUB_OUTPUT
44+
if [[ "${{ github.event_name }}" == 'pull_request_target' || "${{ github.event_name }}" == 'pull_request' ]]; then
45+
target_folder="pr-${{ github.event.pull_request.number }}"
4846
else
49-
echo "target_folder=/" >> $GITHUB_OUTPUT
47+
target_folder="${{github.ref_name}}"
5048
fi
51-
- name: Prepare
49+
echo "target_folder=$target_folder" >> $GITHUB_OUTPUT
50+
51+
- name: Prepare the deploy folder
5252
shell: bash
5353
run: |
5454
# Prepare the deploy folder
55-
mkdir -p deploy_root/${{ steps.calc.outputs.target_folder }}
55+
mkdir -p deploy_root
56+
mkdir -p version_root
5657
# Move the files to the deploy folder
57-
mv ${{ inputs.source_folder }}/* deploy_root/${{ steps.calc.outputs.target_folder }}
58+
mv ${{ inputs.source_folder }}/* deploy_root/
5859
# Ensure that the folder is not treated as a Jekyll site
5960
touch deploy_root/.nojekyll
6061
6162
# Add the target folder to the versions file
62-
git fetch origin gh-pages --depth 1
63-
git checkout origin/gh-pages -- "${{ inputs.versions_file }}"
63+
BASE_REPO="https://github.com/${{ github.repository }}.git"
64+
65+
echo "Fetching gh-pages from BASE_REPO: $BASE_REPO"
66+
git remote add base "$BASE_REPO" || git remote set-url base "$BASE_REPO"
67+
git fetch base gh-pages --depth 1
68+
69+
# Checkout only the versions file from gh-pages branch of the base repo
70+
git checkout base/gh-pages -- "${{ inputs.versions_file }}"
6471
6572
target="${{ steps.calc.outputs.target_folder }}"
66-
if [ "$target" = "/" ]; then
67-
new_version="stable"
68-
else
69-
new_version="$target"
70-
fi
73+
new_version="${{ steps.calc.outputs.target_folder }}"
74+
7175
7276
if jq -e --arg version "$new_version" 'map(select(.version == $version)) | length > 0' "${{ inputs.versions_file }}" > /dev/null; then
7377
echo "Version '$new_version' already exists in ${{ inputs.versions_file }}"
@@ -84,16 +88,29 @@ runs:
8488
jq --arg version "$new_version" --arg url "$new_url" '. + [{"version": $version, "url": $url}]' "${{ inputs.versions_file }}" > tmp_versions.json
8589
mv tmp_versions.json "${{ inputs.versions_file }}"
8690
fi
87-
mv "${{ inputs.versions_file }}" deploy_root/
91+
mv "${{ inputs.versions_file }}" version_root/
8892
ls -al .
8993
ls -al deploy_root
90-
- name: Deploy 🚀
94+
ls -al version_root
95+
cat version_root/"${{ inputs.versions_file }}"
96+
97+
- name: Deploy Documentation
9198
uses: JamesIves/github-pages-deploy-action@v4
9299
with:
93100
folder: deploy_root
101+
target-folder: ${{ steps.calc.outputs.target_folder }}
102+
clean: true
103+
clean-exclude: .nojekyll
104+
105+
- name: Deploy version file 🚀
106+
uses: JamesIves/github-pages-deploy-action@v4
107+
with:
108+
folder: version_root
94109
clean: false
110+
111+
95112
- name: Comment on PR with docs URL
96-
if: ${{ github.event_name == 'pull_request' && inputs.create_comment == 'true' }}
113+
if: ${{ github.event_name == 'pull_request_target' && inputs.create_comment == 'true' }}
97114
uses: peter-evans/create-or-update-comment@v4
98115
with:
99116
issue-number: ${{github.event.pull_request.number}}

‎.github/workflows/docs-cleanup.yml‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
# *******************************************************************************
2-
# Copyright (c) 2024 Contributors to the Eclipse Foundation
2+
# Copyright (c) 2025 Contributors to the Eclipse Foundation
33
#
44
# See the NOTICE file(s) distributed with this work for additional
55
# information regarding copyright ownership.
@@ -13,7 +13,7 @@
1313

1414
name: Cleanup Documentation
1515
on:
16-
pull_request:
16+
pull_request_target:
1717
types: [closed]
1818
delete:
1919
jobs:
@@ -28,7 +28,9 @@ jobs:
2828
steps:
2929
- uses: actions/checkout@v4
3030
with:
31+
repository: ${{ github.event.pull_request.base.repo.full_name }} # Ensures we checkout the base repo, not the fork
3132
ref: gh-pages
33+
fetch-depth: 0
3234
- name: Remove version
3335
run: |
3436
if [[ ${{ github.event_name }} == "pull_request" ]]; then

‎.github/workflows/docs.yml‎

Lines changed: 56 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
# *******************************************************************************
2-
# Copyright (c) 2024 Contributors to the Eclipse Foundation
2+
# Copyright (c) 2025 Contributors to the Eclipse Foundation
33
#
44
# See the NOTICE file(s) distributed with this work for additional
55
# information regarding copyright ownership.
@@ -13,32 +13,64 @@
1313

1414
name: Documentation
1515
on:
16-
pull_request:
17-
types: [opened, reopened, synchronize]
16+
pull_request_target:
17+
types: [opened, reopened, synchronize] # Handles forked PRs
1818
push:
1919
merge_group:
2020
types: [checks_requested]
21+
2122
jobs:
2223
docs-build:
2324
name: Build documentation
2425
runs-on: ubuntu-latest
2526
permissions:
2627
pull-requests: write
2728
steps:
28-
- name: Checkout repository
29+
# ------------------------------------------------------------------------------
30+
# Checkout the correct branch safely in all scenarios (PRs, forks, merges)
31+
# ------------------------------------------------------------------------------
32+
# | Condition | Event Type | Checked Out Branch |
33+
# |----------------------------------------|--------------------|-----------------------|
34+
# | github.head_ref | pull_request_target | PR branch (source branch) |
35+
# | github.event.pull_request.head.ref | pull_request | PR branch (source branch) |
36+
# | github.ref | push, merge_group | The branch being pushed/merged |
37+
# ------------------------------------------------------------------------------
38+
# ------------------------------------------------------------------------------
39+
# Checkout the correct repository safely in all scenarios (PRs, forks, merges)
40+
# ------------------------------------------------------------------------------
41+
# | Condition | Event Type | Checked Out Repository |
42+
# |------------------------------------------------|--------------------|----------------------------------|
43+
# | github.event.pull_request.head.repo.full_name | pull_request | Forked repository (if PR is from a fork) |
44+
# | github.repository | push, merge_group | Default repository (same repo PRs, merges, pushes) |
45+
- name: Checkout repository (Handle all events)
2946
uses: actions/checkout@v4.2.2
47+
with:
48+
ref: ${{ github.head_ref || github.event.pull_request.head.ref || github.ref }}
49+
repository: ${{ github.event.pull_request.head.repo.full_name || github.repository }}
50+
- name: Ensure GitHub Token is Masked
51+
run: echo "::add-mask::$GITHUB_TOKEN"
3052
- name: Setup Bazel
3153
uses: bazel-contrib/setup-bazel@0.9.1
3254
- name: Build documentation
3355
run: |
3456
bazel build //docs:github-pages && cp bazel-bin/docs/github-pages.tar .
57+
# ------------------------------------------------------------------------------
58+
# Generate a unique artifact name to ensure proper tracking in all scenarios
59+
# ------------------------------------------------------------------------------
60+
# | Condition | Event Type | Artifact Name Value |
61+
# |-----------------------------------------------|------------------------|----------------------------------------------|
62+
# | github.event.pull_request.head.sha | pull_request | PR commit SHA (ensures uniqueness per PR) |
63+
# | github.event.pull_request.head.sha | pull_request_target | PR commit SHA (ensures uniqueness per PR) |
64+
# | github.sha | push, merge_group | Current commit SHA (used for main branch) |
65+
# ------------------------------------------------------------------------------
3566
- name: Upload artifact for job analysis
3667
uses: actions/upload-artifact@v4.4.0
3768
with:
38-
name: github-pages-${{ github.sha }}
69+
name: github-pages-${{ github.event.pull_request.head.sha || github.sha }}
3970
path: github-pages.tar
4071
retention-days: 1
4172
if-no-files-found: error
73+
4274
docs-deploy:
4375
name: Deploy documentation to GitHub Pages
4476
permissions:
@@ -52,26 +84,35 @@ jobs:
5284
runs-on: ubuntu-latest
5385
needs: docs-build
5486
steps:
55-
# Checkout is required to get the local actions.
87+
# ------------------------------------------------------------------------------
88+
# Always checks out the BASE repository since pull_request_target is used.
89+
# This ensures that the workflow runs with trusted code from the base repo,
90+
# even when triggered by a pull request from a fork.
91+
# ------------------------------------------------------------------------------
5692
- name: Checkout repository
5793
uses: actions/checkout@v4.2.2
94+
5895
- name: Download documentation artifact
5996
uses: actions/download-artifact@v4.1.8
97+
# ------------------------------------------------------------------------------
98+
# Generate a unique artifact name to ensure proper tracking in all scenarios
99+
# ------------------------------------------------------------------------------
100+
# | Condition | Event Type | Artifact Name Value |
101+
# |-----------------------------------------------|------------------------|----------------------------------------------|
102+
# | github.event.pull_request.head.sha | pull_request | PR commit SHA (ensures uniqueness per PR) |
103+
# | github.event.pull_request.head.sha | pull_request_target | PR commit SHA (ensures uniqueness per PR) |
104+
# | github.sha | push, merge_group | Current commit SHA (used for main branch) |
105+
# ------------------------------------------------------------------------------
60106
with:
61-
name: github-pages-${{ github.sha }}
107+
name: github-pages-${{ github.event.pull_request.head.sha || github.sha }}
108+
62109
- name: Untar documentation artifact
63110
run: mkdir -p extracted_docs && tar -xf github-pages.tar -C extracted_docs
111+
64112
- name: Deploy 🚀
65113
id: pages-deployment
66114
continue-on-error: true
67115
uses: ./.github/actions/deploy-versioned-pages
68116
with:
69117
source_folder: extracted_docs
70-
- name: Deploy (fallback) 🚀
71-
id: deployment
72-
# If the new deployment from gh-pages branch fails, at least deploy the current version.
73-
# This is only a short-term solution, until we can change the repository settings.
74-
if: ${{ steps.pages-deployment.outcome == 'failure' && github.event_name == 'push' && github.ref_name == 'main' }}
75-
uses: actions/deploy-pages@v4.0.5
76-
with:
77-
artifact_name: github-pages-${{ github.sha }}
118+

0 commit comments

Comments
 (0)