Explain how an action can dynamically determine its GITHUB_TOKEN permissions #19323

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://github.com/proxy/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.