Improve descriptions of job/workflow permissions

[mlschechter]

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?

The following documentation pages are affected:

• https://docs.github.com/en/actions/using-jobs/assigning-permissions-to-jobs
• https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idpermissions

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

The articles on job permissions for Workflows and Actions list a number of permissions. It would be helpful if this documentation was updated to detail (or link to, if it already exists) what each of these permissions controls in terms of step execution.

For example, it would be much clearer if it was documented exactly what the pull-requests permission provided access to. This would also allow Action authors to specify the relevant permissions in their documentation, simplifying implementation for workflow creators.

As near as I can tell, some permissions map to the GitHub REST API, others to sub-functions of those resources, and still others to different types of content (like contents). Having a centralized mapping that describes all of these functions makes it easier for Action developers to implement and for workflow developers to consume those Actions with much less trial-and-error testing.

Additional information

It appears that the documentation in question is provided by a reusable file, so the changes would only need to be made in one place.

[welcome[bot]]

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]

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

[jc-clark]

✨ 👋 Hey @mlschechter. We agree that these permissions need some improvement. I'm going to close this issue out because we're now tracking this internally so that we can work with key stakeholders to improve these descriptions.

Thank you for raising this issue!