Improve maintainability of docs build by making docs preview use latest tooling

[AlexanderLanin]

Currently "all the important PRs" cannot be previewed, as half of the job is running from main branch for security reasons. That's extremely annoying. We need to come up with a more elaborate concept, e.g. run from PR if the author is trusted / if approved by a maintainer. E.g. by determining the author, by protected environments, by a custom PR comment, ... whatever.

Example:

• Use 'process_description' as Process score#1192

[nicu1989]

Could we build the docs in the PR context(on pull_request) and publish in the main branch context(on pull_request_target)?

We only have on pull_request_target because we cannot publish to gh-pages otherwise.

The only real issue that I see is the synchronization mechanism between the build and publish jobs. I am thinking on having publish job waiting and pooling on build job to be completed. The classic sync mechanism does not work as the both jobs need to be in the same context.

[AlexanderLanin]

Sounds reasonable!

Here is the GitHub environments idea in more detail:

• Put a token with more access rights into a protected GitHub Environment
• Make the publish workflow run in that context, therefore it will only start when CODEOWNERS explicitly approve job execution
• Bonus: make a clever distinction: Use the above when the PR is from a fork. Build normally when the PR is from a branch.