Fine grained access token instructions in the github actions repository_dispatch documentation

[Denubis]

Code of Conduct

• I have read and agree to the GitHub Docs project's Code of Conduct

What article on docs.github.com is affected?

https://docs.github.com/en/rest/repos/repos?apiVersion=2022-11-28#create-a-repository-dispatch-event via https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#repository_dispatch

What part(s) of the article would you like to see updated?

At present, the documentation for repo_dispatch indicates that the token needs "repo" scope. Using the fine-grained-actions (beta), it took me a fair amount of time to confirm that Actions: read and write is sufficient to make a webhook invocation token. While fine-grained-actions is still in beta, it may be worth updating this documentation.

Specifically, the most important action permission, [POST /repos/{owner}/{repo}/actions/workflows/{workflow_id}/dispatches](https://docs.github.com/en/rest/reference/actions#create-a-workflow-dispatch-event) (write) is third from the bottom, and I had to resort to ctrl-f to find it, which is why I wasn't certain that this was the correct permission. I'm now testing to see if this finely scoped permission is also sufficient for the task.

Additional information

Update: It turns out that that permission is necessary, but not sufficient. It would be nice to have the full minimum set of permissions necessary in repository_dispatch to trigger one.

[welcome]

Thanks for opening this issue. A GitHub docs team member should be by to give feedback soon. In the meantime, please check out the contributing guidelines.

[cmwilson21]

@Denubis Thanks so much for opening an issue! I'll triage this for the team to take a look 👀

[Denubis]

@cmwilson21 Also, in conversation with a colleague, the "repo" permission on the classic version seems large-scoped for "needing to call a webhook" -- nuance as to what the minimal set of permissions required for "simple webhook invocation" both classic and new would be very much appreciated.

[Denubis]

Ok, extra update. While testing the beta perms for something that involved variables and secrets, I used

6 permissions for 1 of your repositories
Actions
Access: Read and write
Contents
Access: Read and write
Metadata
Access: Read-only
Secrets
Access: Read and write
Variables
Access: Read and write
Workflows
Access: Read and write

And it worked. Not sure it's the minimum possible scope, but since my github action involves variables and secrets, I guessed at this? (I'm not sure why the invoking webhook needs all this access, or if it does). But it might help your docs folk start somewhere.

[Princexz]

6 permissions for 1 of your repositories

Actions

Access: Read and write

Contents

Access: Read and write

Metadata

Access: Read-only

Secrets

Access: Read and write

Variables

Access: Read and write

Workflows

Access: Read and write

[skedwards88]

Thanks for this issue! This article describes the permissions required for fine-grained personal access tokens. We have an internal issue to make this information more discoverable and to keep this information automatically up-to-date, so I'm going to close out this issue.

[Denubis]

Thanks @skedwards88 -- one note I'd like to make is that the article you linked was not useful to me when trying to figure out permission sets. There was a fair amount of cutting-and-trying. The naive approach (select actions) was insufficient, and the original article was not useful. For the internal issue, if you could flag: "The minimum necessary set to launch an external webhook which references repository secrets" -- that would be wonderful. As a larger bit of feedback, having a "trigger a webhook on selected repositories only" permission-option would be quite useful from a security perspective, as these secrets have much higher potential exposure.

In any event, thanks for the response and I hope you both have a great weekend.