feat(ci): add PR preview deployment workflow

[mgajek-cern]

Addresses #658

---

Some additional information:

Testing & Verification

Fork-to-Fork Testing

To verify the pull_request_target workflow with fork PRs, we conducted the following experiment:

1. Setup fork chain:

   • Merged preview workflow into mgajek-cern/documentation main branch (required for pull_request_target to run)
   • Created fork: MGTheTrain/documentation synced with mgajek-cern/documentation
   • Created 3 test branches in MGTheTrain/documentation to verify workflow behavior

2. Verified deployment functionality:

   • Opened PRs from MGTheTrain/documentation → mgajek-cern/documentation
   • Confirmed workflow creates preview deployments with sticky comments:

     🚀 Preview Deployed
     Preview URL: https://mgajek-cern.github.io/documentation/pr-preview/pr-6/
     Built from commit: d17cf2c

• Checkout sticky notes in example PRs: Update 1 mgajek-cern/documentation#5, Update 2 mgajek-cern/documentation#6, Update 3 mgajek-cern/documentation#7

3. Verified cleanup functionality:
   • Closed and merged test PR
   • Confirmed preview directory removed from gh-pages branch
   • Checkout sticky notes in example PRs: [TEMP] Verify workflow behavior trough a fork-pull request mgajek-cern/documentation#2

Next Steps

1. Merge this PR into upstream rucio/documentation
2. Verify identical behavior with actual fork PRs from contributors
3. If permission issues arise (unlikely, as PAT is from org member mgajek-cern), consider using service account PAT

Note: The PREVIEW_TOKEN PAT has full repo and workflow permissions and is created by an org member, so cross-fork deployment should work as demonstrated. PREVIEW_TOKEN is configured as a GitHub secret: https://github.com/rucio/documentation/settings/secrets/actions

[voetberg]

Does this use your own account to post the sticky comments? Maybe a link included in the CI would be cleaner. I don't love the idea of the action using your account to make comments on your behalf.

[mgajek-cern]

Does this use your own account to post the sticky comments? Maybe a link included in the CI would be cleaner. I don't love the idea of the action using your account to make comments on your behalf.

Good point about the account visibility. Ideally, we'll replace the current PREVIEW_TOKEN (which uses my personal PAT) with a PAT from a Rucio organization service account for the rucio/documentation repo, assuming one exists with the necessary permissions.

About the CI link: Since the sticky comment already displays the preview URL directly in the PR (where developers typically check first), including it in the CI logs feels unnecessary. That said, if you'd prefer having it in the CI output too (using an echo statement or similar) for quick access from the Actions tab, I'll add that. Just let me know if you want it in both places.

[voetberg]

Does this use your own account to post the sticky comments? Maybe a link included in the CI would be cleaner. I don't love the idea of the action using your account to make comments on your behalf.

Good point about the account visibility. Ideally, we'll replace the current PREVIEW_TOKEN (which uses my personal PAT) with a PAT from a Rucio organization service account for the rucio/documentation repo, assuming one exists with the necessary permissions.

About the CI link: Since the sticky comment already displays the preview URL directly in the PR (where developers typically check first), including it in the CI logs feels unnecessary. That said, if you'd prefer having it in the CI output too (using an echo statement or similar) for quick access from the Actions tab, I'll add that. Just let me know if you want it in both places.

Sorry for the lack of clarity there, I meant either-or. If we have a service account post it instead that would be fine!

[mgajek-cern]

Sorry for the lack of clarity there, I meant either-or. If we have a service account post it instead that would be fine!

Perfect, thanks for clarifying. I couldn't find an existing service account. I'll ask if we should create one (e.g. rucio-bot or rucio-ci) and request the organization admins to set it up.

If that's not feasible, we could fall back to showing the preview URL only in CI logs (as you suggested) instead of PR comments. That would avoid the personal account issue, though it's less visible and requires extra clicks to access compared to sticky comments in the PR.

[mgajek-cern]

Sorry for the lack of clarity there, I meant either-or. If we have a service account post it instead that would be fine!

Perfect, thanks for clarifying. I couldn't find an existing service account. I'll ask if we should create one (e.g. rucio-bot or rucio-ci) and request the organization admins to set it up.

If that's not feasible, we could fall back to showing the preview URL only in CI logs (as you suggested) instead of PR comments. That would avoid the personal account issue, though it's less visible and requires extra clicks to access compared to sticky comments in the PR.

@bari12: Should we create a service account (e.g. rucio-bot or rucio-ci) for this or fall back to showing the preview URL only in the CI logs? If we go with a service account, who could set it up?