docs: preview in PRs from forks

[AlexanderLanin]

Problem Description
Currently PRs from forks do not have any kind of preview for the generated documentation.

The workflow is established, but it has insufficient access rights when the PR stems from a fork. Detailed explanation and potential solution at eclipse-score/.eclipsefdn#11

Task:

• Understand the solution
• Either break down the solution into sub-issues or implement it, depending on required effort

[dcalavrezo-qorix]

Apparently this is by design to prevent security risks from malicious PRs.

• When a PR comes from a fork, GitHub blocks GITHUB_TOKEN from writing to protected branches (like gh-pages).
• Even with pull_request_target, GitHub restricts direct pushes to the same repository (eclipse-score/score).

A safe alternative would be to create a separate repository - something like score-previews where only the previews from PR are pushed.
Then the requests would be served from another URL, like https://eclipse-score.github.io/score-previews

The https://eclipse-score.github.io/score would only hold main and releases.

This would avoid cluttering the gh-pages ( although in theory they are deleted when the PR is merged).

Nevertheless, we could still try the following:

1. Use pull_request_target instead of pull_request, which (theoretically - there are some contradictions - see above) runs in the context of the base repository, allowing it to get write permissions.
2. Create a DEPLOY_PREVIEW_TOKEN which we could store in the score secrets
   This can be passed as a parameter to the github-pages-deploy-action

[dcalavrezo-qorix]

Fine grained PATs do not allow branch restrictions sadly. So we could in theory create a DEPLOY_PREVIEW_TOKEN, but GH doesn't allow for it to be restricted to a specific branch ( gh-pages for us)

[dcalavrezo-qorix]

The github-pages-deploy-action also allows ssh-key usage

So, one could:

1. generate a ssh-key

ssh-keygen -t ed25519 -C "GitHub Pages Actions Deploy Key" -f gh-pages-deploy-key

2, add the public key to GH

• in the repo → Settings → Deploy Keys.
• Click Add deploy key.
• Title: gh-pages Deploy Key
• Paste the contents of gh-pages-deploy-key.pub.
• Check "Allow write access"
• Save.

3. store the private key as a secret

• In the repo -> go to -> Settings → Secrets and variables → Actions.
• Click New repository secret.
• Name: DEPLOY_PREVIEW_SSH_KEY
• Value: Paste the private key from gh-pages-deploy-key.
• Save.

4. modify the GH action

${{ secrets.DEPLOY_PREVIEW_SSH_KEY }}

[AlexanderLanin]

Is an Environment secret also a viable alternative? With review by "trusted contributors" before the action starts. Just collecting ideas.