Token permissions should link to more detailed information

[simonw]

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/actions/artifacts?apiVersion=2022-11-28#get-an-artifact

What changes are you suggesting?

On this page: https://docs.github.com/en/rest/actions/artifacts?apiVersion=2022-11-28#get-an-artifact

It says this:

The fine-grained token must have the following permission set:

• "Actions" repository permissions (read)

That's not quite enough information. I ended up having to add this YAML to my workflow to get a token that worked, for example:

permissions:
  actions: read

It would be useful if the text "Actions" repository permissions (read) included a link to super detailed documentation about that specific permission which included exactly how to issue tokens with it (ideally with screenshots of the UI because I always get lost in those kinds of interfaces) and details about what that looks like in YAML configuration too.

Additional information

No response

[Sharra-writes]

@simonw Thanks for opening an issue! We're currently at the beginning of a big docs reorganization, and I don't know if anyone has the bandwidth for writing this right now, but I will definitely check in with the team. It might be something we add to our backlog to include down the road when our initial dividing up and sorting of articles is finished, depending on how much perceived demand there is for this kind of tutorial. I'll find out and let you know.

Edit: Sorry, I initially saw "actions" and missed "rest." REST API content is largely auto-generated, so I will still check in about this, but it may need to be closed here and opened internally for review.

[github-actions]

A stale label has been added to this issue, because it has been open for 30 days with no activity. If you think this issue should remain open, please add a new comment.

[docs-bot]

Thank you for opening this issue! Updates to this documentation must be made internally. I have copied your issue to an internal issue, so I will close this issue.

[Sharra-writes]

@simonw This got lost in my pile for a bit, because I needed to sift through our documentation to see if we had what you were asking for (the answer is "kind of"). It does need to be handled internally and I'll give the team responsible links to the documentation I found, so they can decide if/how to integrate it. I can't tell you what their decision will be, but I'll at least make sure they have the resources to make a decision.