From 09c215fe99ae3ec3d551e0df2d0acbe83629e8cc Mon Sep 17 00:00:00 2001 From: Brad Jorsch Date: Mon, 16 Dec 2024 14:52:30 -0500 Subject: [PATCH] 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 | 8 ++++++++ .../update-github-actions-docs-with-permissions | 4 ++++ projects/github-actions/required-review/README.md | 13 ++++++++++--- .../update-github-actions-docs-with-permissions | 4 ++++ .../github-actions/test-results-to-slack/README.md | 8 ++++++++ .../update-github-actions-docs-with-permissions | 4 ++++ 6 files changed, 38 insertions(+), 3 deletions(-) create mode 100644 projects/github-actions/pr-is-up-to-date/changelog/update-github-actions-docs-with-permissions create mode 100644 projects/github-actions/required-review/changelog/update-github-actions-docs-with-permissions create mode 100644 projects/github-actions/test-results-to-slack/changelog/update-github-actions-docs-with-permissions diff --git a/projects/github-actions/pr-is-up-to-date/README.md b/projects/github-actions/pr-is-up-to-date/README.md index d836b4914f75c..1bb52eed66124 100644 --- a/projects/github-actions/pr-is-up-to-date/README.md +++ b/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 diff --git a/projects/github-actions/pr-is-up-to-date/changelog/update-github-actions-docs-with-permissions b/projects/github-actions/pr-is-up-to-date/changelog/update-github-actions-docs-with-permissions new file mode 100644 index 0000000000000..41e21f7c7a781 --- /dev/null +++ b/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. diff --git a/projects/github-actions/required-review/README.md b/projects/github-actions/required-review/README.md index 1eb49ded89baa..8a9a0699ac5ad 100644 --- a/projects/github-actions/required-review/README.md +++ b/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: diff --git a/projects/github-actions/required-review/changelog/update-github-actions-docs-with-permissions b/projects/github-actions/required-review/changelog/update-github-actions-docs-with-permissions new file mode 100644 index 0000000000000..41e21f7c7a781 --- /dev/null +++ b/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. diff --git a/projects/github-actions/test-results-to-slack/README.md b/projects/github-actions/test-results-to-slack/README.md index fb845da77fac9..6837b229475a4 100644 --- a/projects/github-actions/test-results-to-slack/README.md +++ b/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: diff --git a/projects/github-actions/test-results-to-slack/changelog/update-github-actions-docs-with-permissions b/projects/github-actions/test-results-to-slack/changelog/update-github-actions-docs-with-permissions new file mode 100644 index 0000000000000..41e21f7c7a781 --- /dev/null +++ b/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.