docs: enable pull requests to publish a preview

[AlexanderLanin]

We have an action running, which will publish pull request previews into /pr-123 subdirectories in gh-pages. However that action currently cannot push to gh-pages branch.

GITHUB_TOKEN is currently allowed to push to branches when running for branch builds, but it's disabled when running from PR builds. This PR adjusts the relevant setting.

note: there is contradicting information on the internet regarding how 'default workflow permissions' behave. But it seems (as evidenced in this case), that the interpretation of it serving as a maximum is correct. Workflows cannot elevate themselves to write, when the default is set to read-only.

If your repository's Actions permissions setting is set to "Read repository contents permission" (default), the permissions block in the workflow cannot elevate permissions to write.
The permissions block refines or restricts permissions within the limits set by the repository settings. It cannot bypass those limits.

Examples of default_workflow_permissions in combination with gh-pages:

• https://github.com/eclipse-keypop/.eclipsefdn/blob/d302a93a17bc42ed08f6b65d70d220c601d6c4b8/otterdog/eclipse-keypop.jsonnet#L482
• https://github.com/eclipse-zenoh/.eclipsefdn/blob/44c59e2d14f68f4fa556f6fb622090a1d7890e5b/otterdog/eclipse-zenoh.jsonnet#L322
• https://github.com/eclipse-keyple/.eclipsefdn/blob/0a852bb5befffc7f9002008beb15b1d261e3ab52/otterdog/eclipse-keyple.jsonnet#L95
• https://github.com/eclipse-thingweb/.eclipsefdn/blob/c21814d81fe5f7bc06ffd58bd8b3ef661032fe52/otterdog/eclipse-thingweb.jsonnet#L50

[eclipse-otterdog]

Thank you for raising a pull request to update the configuration of your GitHub organization.
You can manually add reviewers to this PR to eventually enable auto-merging.

The following conditions need to fulfilled for auto-merging to be available:

• valid configuration
• approved by a project lead
• does not require any secrets
• does not update settings only accessible via the GitHub Web UI
• does not remove any resource

Otterdog commands and options

You can trigger otterdog actions by commenting on this PR:

• /otterdog team-info checks the team / org membership for the PR author
• /otterdog validate validates the configuration change
• /otterdog validate info validates the configuration change, printing also validation infos
• /otterdog check-sync checks if the base ref is in sync with live settings
• /otterdog merge merges and applies the changes if the PR is eligible for auto-merging (only accessible for the author)
• /otterdog done notifies the self-service bot that a required manual apply operation has been performed (only accessible for members of the admin team)
• /otterdog apply re-apply a previously failed attempt (only accessible for members of the admin team)

[eclipse-otterdog]

The author (AlexanderLanin) of this PR is associated with this organization in the role of NONE.

[netomi]

/otterdog validate info

[eclipse-otterdog]

Please find below the validation of the requested configuration changes:

Diff for 70ece1c

Project automotive.score[github_id=eclipse-score]
+                                                                                                             
+ Info:   repository[name=".github"] has 'actions_can_approve_pull_request_reviews' enabled, while on         
+         organization level it is disabled, setting will be ignored.                                         
+                                                                                                             
+                                                                                                             
+ Info:   repository[name="bazel_registry"] has 'actions_can_approve_pull_request_reviews' enabled, while on  
+         organization level it is disabled, setting will be ignored.                                         
+                                                                                                             
+                                                                                                             
+ Info:   repository[name="eclipse-score.github.io"] has 'actions_can_approve_pull_request_reviews' enabled,  
+         while on organization level it is disabled, setting will be ignored.                                
+                                                                                                             
+                                                                                                             
+ Info:   repository[name="inc_feo"] has 'actions_can_approve_pull_request_reviews' enabled, while on         
+         organization level it is disabled, setting will be ignored.                                         
+                                                                                                             
+                                                                                                             
+ Info:   repository[name="inc_mw_com"] has 'actions_can_approve_pull_request_reviews' enabled, while on      
+         organization level it is disabled, setting will be ignored.                                         
+                                                                                                             
+                                                                                                             
+ Info:   repository[name="inc_mw_log"] has 'actions_can_approve_pull_request_reviews' enabled, while on      
+         organization level it is disabled, setting will be ignored.                                         
+                                                                                                             
+                                                                                                             
+ Info:   repository[name="inc_mw_per"] has 'actions_can_approve_pull_request_reviews' enabled, while on      
+         organization level it is disabled, setting will be ignored.                                         
+                                                                                                             
+                                                                                                             
+ Info:   repository[name="process_description"] has 'actions_can_approve_pull_request_reviews' enabled,      
+         while on organization level it is disabled, setting will be ignored.                                
+                                                                                                             
+                                                                                                             
+ Info:   repository[name="reference_integration"] has 'actions_can_approve_pull_request_reviews' enabled,    
+         while on organization level it is disabled, setting will be ignored.                                
+                                                                                                             
+                                                                                                             
+ Info:   repository[name="score"] has 'default_workflow_permissions' of value 'write', while on              
+         organization level it is restricted to 'read', setting will be ignored.                             
+                                                                                                             
+                                                                                                             
+ Info:   repository[name="score"] has 'actions_can_approve_pull_request_reviews' enabled, while on           
+         organization level it is disabled, setting will be ignored.                                         
+                                                                                                             
  
  Plan: 0 to add, 0 to change, 0 to delete.

[netomi]

so overwriting specific settings on repo level while on org level it is more restricted does not work and the setting will be ignored.

In your case, you should adapt the workflow to specify the required permission it needs, see https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/controlling-permissions-for-github_token

[AlexanderLanin]

@netomi sorry I was unclear. That's what we tried already. It doesn't help. And it seems this does not work because it cannot have more access than the "default". At least that's how I understand it at the moment.

https://github.com/eclipse-score/score/blob/6991a3e00a97c0e74df267f74b9e88b3137b56ef/.github/workflows/docs.yml#L44-L47

[netomi]

it does not work for PRs from forks. In such cases the workflow will not get write tokens. This is the default behavior of GitHub. So there are workarounds that we applied for several projects, see for example https://github.com/eclipse-langium/langium-website/blob/main/.github/workflows/preview.yml