Research if there is any fix to race condition in PR preview deployment with GitHub Pages

Problem

We periodically have gotten PR deployment failures in the poll_deployment.py step. They've always happened, but have been much worse in the past month, which I now realize is because of how much activity this repo has had.

It turns out that the issue is a race condition with PRs concurrently requesting a deployment with GitHub Pages to the same environment. This results in GitHub Actions cancelling the deployment

That happens in the deploy step with actions/deploy-pages@v4, e.g. in https://github.com/Qiskit/documentation/actions/runs/15691700791/job/44208343380

Run actions/deploy-pages@v4
  with:
    token: ***
    timeout: 600000
    error_count: 10
    reporting_interval: 5000
    artifact_name: github-pages
    preview: false
Fetching artifact metadata for "github-pages" in this workflow run
Found 1 artifact(s)
Creating Pages deployment with payload:
{
	"artifact_id": 3339897245,
	"pages_build_version": "0226b2635e7e28044e7fc62819dd1059f27edf1f",
	"oidc_token": "***"
}
Created deployment for 0226b2635e7e28044e7fc62819dd1059f27edf1f, ID: 0226b2635e7e28044e7fc62819dd1059f27edf1f
Getting Pages deployment status...
Current status: deployment_in_progress
Getting Pages deployment status...
Current status: deployment_in_progress
Getting Pages deployment status...
Current status: deployment_in_progress
Getting Pages deployment status...
Current status: deployment_in_progress
Canceling Pages deployment...
Canceled deployment with ID 0226b2635e7e28044e7fc62819dd1059f27edf1f
Error: The operation was canceled.

Those logs correspond to https://github.com/actions/deploy-pages/blob/854d7aa1b99e4509c4d1b53d69b7ba4eaf39215a/src/index.js#L12 and https://github.com/actions/deploy-pages/blob/854d7aa1b99e4509c4d1b53d69b7ba4eaf39215a/src/internal/deployment.js#L219, which are triggered specifically when GH Actions cancels the workflow.

Any solution?

Is there any mechanism to address this race condition, such as locking? Note that the issue is happening at the GH Actions level.

Should we also lower our timeout here now that we realize the issue is a race condition? Waiting 3m to fail is overkill:

https://github.com/Qiskit/documentation/blob/ccb7a269eb6f38864bd21e0134c28c1ac6e4452a/scripts/pr-previews/poll_deployment.py#L27

Maybe revert https://github.com/Qiskit/documentation/pull/2016

Start with scripts/pr-previews/poll_deployment.py at line 27 and the deploy step using actions/deploy-pages@v4. Review the linked deploy-pages implementation and the referenced workflow run to understand how cancellation occurs when PR deployments overlap. Done means documenting whether GitHub Actions provides a suitable lock, and whether the timeout or PR #2016 should change.