actions: Document fine-grained permissions (#40633)

We had documented the OAuth-style scopes where it was likely to matter,
but never mentioned the newer "permissions" for GitHub Apps and
fine-grained access tokens.

projects/github-actions/pr-is-up-to-date/README.md

@@ -41,6 +41,14 @@ jobs:
 This action is intended to be triggered by `pull_request_target` or `pull_request` targeting the specified branch, and by a `push` to the specified tags.
 It will not work for pushes to anything else.
 
+### Permissions required
+
+This action needs access to read pull request data and create status checks.
+
+For OAuth apps and classic access tokens, that's `repo:status`.
+
+For GitHub Apps and fine-grained access tokens, that's read and write for repository "Commit statuses" (`statuses`) and read-only for "Pull requests" (`pull-requests`).
+
 ### On pull request
 
 ```yaml

projects/github-actions/pr-is-up-to-date/changelog/update-github-actions-docs-with-permissions

@@ -0,0 +1,4 @@
+Significance: patch
+Type: changed
+
+Update docs with permissions for GitHub Apps and fine-grained access tokens.

projects/github-actions/required-review/README.md

@@ -70,12 +70,19 @@ This action is intended to be triggered by the `pull_request_review` event.
     request-reviews: true
 
     # GitHub Access Token. The user associated with this token will show up
-    # as the "creator" of the status check, and must have access to read
-    # pull request data, create status checks (`repo:status`), and to read
-    # your organization's teams (`read:org`).
+    # as the "creator" of the status check, and must have the permissions
+    # documented below.
     token: ${{ secrets.SOME_TOKEN }}
 ```
 
+### Permissions required
+
+This action needs access to read pull request data, request reviewers, create status checks, and to read your organization's teams.
+
+For OAuth apps and classic access tokens, that's `repo:status` and `read:org`.
+
+For GitHub Apps and fine-grained access tokens, that's read and write for repository "Commit statuses" (`statuses`) and "Pull requests" (`pull-requests`), and read-only for organization "Members".
+
 ## Requirements Format
 
 The requirements consist of an array of requirement objects. A requirement object has the following keys:

projects/github-actions/required-review/changelog/update-github-actions-docs-with-permissions

@@ -0,0 +1,4 @@
+Significance: patch
+Type: changed
+
+Update docs with permissions for GitHub Apps and fine-grained access tokens.

projects/github-actions/test-results-to-slack/README.md

@@ -86,6 +86,14 @@ The action relies on the following parameters.
 - (Optional) `playwright_report_path` is the path to the JSON report, output from Playwright test runner JSON reporter. See [Playwright's docs](https://playwright.dev/docs/test-reporters#json-reporter) for details on how to generate this file. If specified, it will be parsed and failures details will be included in the message. You can use the glob pattern to specify multiple files. For example: `playwright_report_path: 'artifacts/**/report.json'`.
 - (Optional) `playwright_output_dir` is the path to the Playwright's configured output directory, where results and attachments are saved. It is needed when the artefacts are downloaded from a previous job, and the absolute paths to attachments found in the JSON report are not valid anymore. This path will be used to convert the paths to those attachments. You can use the glob pattern. For example: `playwright_output_dir: 'artifacts/**/results'`
 
+### GitHub permissions required
+
+This action needs access to list jobs for workflow runs.
+
+For OAuth apps and classic access tokens, no special scopes are needed.
+
+For GitHub Apps and fine-grained access tokens, that's read-only for repository "Actions" (`actions`).
+
 ### Slack token
 
 You will need to [create a Slack bot for your workspace](https://slack.com/intl/en-hu/help/articles/115005265703-Create-a-bot-for-your-workspace) for the action to use. The bot will need the following scopes:

projects/github-actions/test-results-to-slack/changelog/update-github-actions-docs-with-permissions

@@ -0,0 +1,4 @@
+Significance: patch
+Type: changed
+
+Update docs with permissions for GitHub Apps and fine-grained access tokens.