Explain how an action can dynamically determine its `GITHUB_TOKEN` permissions

[jsoref]

Code of Conduct

• [X] 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/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token

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

There's a section about Using the GITHUB_TOKEN in a workflow

And similarly Permissions for the GITHUB_TOKEN

There should be a section that explains how something running with a token can determine what permissions it has from the token.

Additional information

None of this content explains how an action can find out what permissions it actually has. I have an action (and many others do as well) which would like to be able to perform certain tasks (a simple example is actions/labeler). Some organizations disable write permissions to workflows, which means that an action (especially labeler) will fail when run in them. The workflow that uses labeler is likely to be written for its original repository (where it has write permissions), but when the repository is forked to the more restrictive organization, the workflow will malfunction.

If there were an easy way for an action (or workflow) to ask "what permissions do I have", it could either stop early, or at provide helpful error handling instead of just encountering a 404 and dying ungracefully.

[cmwilson21]

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

[janiceilene]

Hey @jsoref I've talked with the team and this is something that would be better to send over to the actions product folks! You can post in the new https://github.com/orgs/community/discussions/categories/actions-and-packages and come back to let us know if there ends up being something to change in the docs ✨

[jsoref]

Filed https://github.com/orgs/community/discussions/61646