Clarify How the permissions are calculated for a workflow job

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/actions/security-guides/automatic-token-authentication#how-the-permissions-are-calculated-for-a-workflow-job

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

Finally,
if the workflow was triggered by a pull request from a forked repository,
and the Send write tokens to workflows from pull requests setting is not selected,
the permissions are adjusted to change any write permissions to read only.

Should be changed to say clarify that if the workflow was triggered by a pull request and the job event is pull_request_target then write permissions will not be changed to read only.

I'm still recovering from a concussion, but here's my first attempt at fixing this text:

Finally,
if the workflow was triggered for the pull_request event (and not the pull_request_target event) by a pull request from a forked repository,
and the Send write tokens to workflows from pull requests setting is not selected,
the permissions are adjusted to change any write permissions to read only.

Additional information

No response

@jsoref

@jsoref Sorry to hear about the concussion 💛 I'll get this triaged for review ✨

Thanks for opening an issue! We've triaged this issue for technical review by a subject matter expert 👀

@jsoref

@jsoref Hello! 👋 Our engineering team reviewed, and agreed with your proposed clarification. They also wanted to mention the following -

The suggested text is not quite right though - the read-only behavior applies to all pull request events triggered on a fork PR except pull_request_target

So it’s not correct to say it only applies to pull_request events, it would apply to pull_request_review and the other PR/issue related events

With that adjustment in mind, you or anyone else is welcome to open a PR with this update ✨

CC @jc-clark just for visibility 💛

@nguyenalex836

Hello @nguyenalex836,

I have read through the conversation and the suggestions from the engineering team. Please review the proposed update for the documentation to clarify the behavior of workflow job permissions. The read-only adjustment applies to all pull request-related events triggered on a fork PR except for the pull_request_target event. This ensures that users understand the specific conditions under which write permissions remain unchanged.

Updated section:

Finally, if the workflow was triggered by a pull request from a forked repository, and the Send write tokens to workflows from pull requests setting is not selected, the permissions are adjusted to change any write permissions to read-only, except for the pull_request_target event. This applies to all pull request-related events, including pull_request_review.

Is this good to go?

@Vikranth3140

@Vikranth3140: the pull_request_review bit was a correction to my mentioning pull_request. I think it's probably best to omit both.

You probably want to include:

For more information, see "[AUTOTITLE](/actions/using-workflows/events-that-trigger-workflows#pull_request_target)."

(That text appears in places like https://docs.github.com/en/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token -- see https://github.com/search?q=repo%3Agithub%2Fdocs%20see%20%22%5BAUTOTITLE%5D(%2Factions%2Fusing-workflows%2Fevents-that-trigger-workflows).%22&type=code)

@subatoi

@subatoi: I think the bot is broken

Navigation Menu

Repository navigation

Clarify `How the permissions are calculated for a workflow job` #32398

Code of Conduct

What article on docs.github.com is affected?

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

Additional information

15 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Clarify How the permissions are calculated for a workflow job #32398

Description

Code of Conduct

What article on docs.github.com is affected?

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

Additional information

Activity

nguyenalex836 commented on Apr 5, 2024

github-actions commented on May 30, 2024

nguyenalex836 commented on Jun 14, 2024

Vikranth3140 commented on Jun 18, 2024

jsoref commented on Jun 18, 2024

15 remaining items

jsoref commented on May 12, 2025

bosshogg276 commented on May 23, 2025

Nutdanai999 commented on Jun 11, 2025

Nutdanai999 commented on Jun 11, 2025

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Clarify `How the permissions are calculated for a workflow job` #32398