ci: deploy pull request previews from a separate privileged workflow

[MattiasBuelens]

Summary

Pull requests from forks (e.g. #870) fail in deploy / deploy-to-cloudfront: pull_request runs from forks get no secrets, no vars, and no OIDC id-token. This splits the PR pipeline into an unprivileged part and a privileged part, following the "preventing pwn requests" pattern.

• pull-request.yml (pull_request, no secrets): lint + build only. The build runs the PR's code (npm ci, Docusaurus plugins), so it must stay unprivileged. docusaurus_url is now hardcoded to the preview origin because vars are empty for forks.
• New pull-request-preview.yml (runs on main, has secrets + OIDC):
  • workflow_run on completion of "On Pull Requests": looks up the open PR whose head is exactly workflow_run.head_sha via GET /repos/{repo}/commits/{sha}/pulls (the event's pull_requests list is empty for forks; the PR number is never read from the artifact so a fork cannot overwrite another PR's preview), downloads the dist.zip artifact from that run, and calls _deploy.yml. It never checks out or runs PR code.
  • pull_request_target on closed: undeploy. Safe because it only uses event metadata, no checkout.
  • Fork PRs deploy to a new preview-fork environment; same-repo PRs keep using preview. This lets preview-fork require reviewer approval without affecting internal PRs.
• _deploy.yml: new optional inputs artifact_run_id, pr_number, pr_head_sha (defaults keep main.yml unchanged). PR-comment steps are gated on pr_number > 0 instead of environment_name == 'preview'. Top-level concurrency moved to the callers as preview-pr-<number> (in workflow_run context github.ref is always main, which would serialize and drop queued deploys across all PRs).

Required setup after merge (repo settings / AWS)

1. Create environment preview-fork and add Required reviewers. Every deploy from a fork will wait for approval. Copy the variables that are scoped to the preview environment (e.g. AWS_REGION, AWS_ROLE, S3_BUCKET_NAME, CF_DISTRIBUTION_ID, if they are not repository-level). Organization-level variables and secrets (THEOPLAYER_BOT_APP_ID, THEOPLAYER_BOT_PRIVATE_KEY) are available to every environment and need no copy.
2. If the AWS role trust policy restricts the OIDC sub claim to environment:preview, also allow repo:THEOplayer/documentation:environment:preview-fork.

Notes

• workflow_run workflows only trigger from the default branch, so this cannot be verified on this PR itself; the first real test is the next PR after merge (Integrate UI customization documentation into OptiView Player #870 can be re-run by pushing to it).
• Residual risk: a fork can publish attacker-authored static HTML under pr-N/ on the preview domain (as any PR can today); the approval step is what gates that.

Link to Devin session: https://dolby.devinenterprise.com/sessions/d49785eb74de44dfbe2baeafe9b73728
Open in Devin Desktop: https://dolby.devinenterprise.com/desktop/session/d49785eb74de44dfbe2baeafe9b73728?variant=devin
Requested by: @MattiasBuelens

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring