Document GITHUB_TOKEN pull request workflow approval behavior (#60926)

Co-authored-by: Joe Clark <31087804+jc-clark@users.noreply.github.com>

Author: salmanmkc

content/actions/concepts/security/github_token.md

@@ -29,6 +29,11 @@ The token is also available in the `github.token` context. For more information,
 
 {% data reusables.actions.actions-do-not-trigger-workflows %}
 
+{% ifversion actions-github-token-pull-request-approval %}
+> [!NOTE]
+> If you need workflow runs from workflow-created pull requests to execute without requiring approval, use a {% data variables.product.prodname_github_app %} installation access token or a {% data variables.product.pat_generic %} instead of `GITHUB_TOKEN` when creating or updating the pull request.
+{% endif %}
+
 {% data reusables.actions.actions-do-not-trigger-pages-rebuilds %}
 
 ## Next steps

content/actions/how-tos/write-workflows/choose-when-workflows-run/trigger-a-workflow.md

@@ -25,7 +25,7 @@ To learn more about workflows and triggering workflows, see [AUTOTITLE](/actions
 
 {% data reusables.actions.actions-do-not-trigger-workflows %} For more information, see [AUTOTITLE](/actions/security-guides/automatic-token-authentication).
 
-If you do want to trigger a workflow from within a workflow run, you can use a {% data variables.product.prodname_github_app %} installation access token or a {% data variables.product.pat_generic %} instead of `GITHUB_TOKEN` to trigger events that require a token.
+If you do want to trigger a workflow from within a workflow run, you can use a {% data variables.product.prodname_github_app %} installation access token or a {% data variables.product.pat_generic %} instead of `GITHUB_TOKEN` to trigger events that require a token.{% ifversion actions-github-token-pull-request-approval %} Using one of these alternatives also lets `pull_request` workflows run automatically (without the approval prompt described above) when the pull request is created or updated by automation.{% endif %}
 
 If you use a {% data variables.product.prodname_github_app %}, you'll need to create a {% data variables.product.prodname_github_app %} and store the app ID and private key as secrets. For more information, see [AUTOTITLE](/apps/creating-github-apps/guides/making-authenticated-api-requests-with-a-github-app-in-a-github-actions-workflow). If you use a {% data variables.product.pat_generic %}, you'll need to create a {% data variables.product.pat_generic %} and store it as a secret. For more information about creating a {% data variables.product.pat_generic %}, see [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). For more information about storing secrets, see [AUTOTITLE](/actions/security-guides/using-secrets-in-github-actions).
 

content/actions/reference/workflows-and-actions/events-that-trigger-workflows.md

@@ -510,7 +510,8 @@ on:
 > [!NOTE]
 > * {% data reusables.developer-site.multiple_activity_types %} For information about each activity type, see [AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads#pull_request). By default, a workflow only runs when a `pull_request` event's activity type is `opened`, `synchronize`, or `reopened`. To trigger workflows by different activity types, use the `types` keyword. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#onevent_nametypes).
 > * Workflows will not run on `pull_request` activity if the pull request has a merge conflict. The merge conflict must be resolved first. Conversely, workflows with the `pull_request_target` event will run even if the pull request has a merge conflict. Before using the `pull_request_target` trigger, you should be aware of the security risks. For more information, see [`pull_request_target`](#pull_request_target).
-> * The `pull_request` webhook event payload is empty for merged pull requests and pull requests that come from forked repositories.
+> * The `pull_request` webhook event payload is empty for merged pull requests and pull requests that come from forked repositories.{% ifversion actions-github-token-pull-request-approval %}
+> * When a pull request is created or updated by a workflow using `GITHUB_TOKEN`, `pull_request` events with the `opened`, `synchronize`, or `reopened` activity types create workflow runs that require approval. A user with write access to the repository can approve these runs from the pull request page. With the exception of `workflow_dispatch` and `repository_dispatch`, other `GITHUB_TOKEN`-triggered events do not create workflow runs at all.{% endif %}
 > * The value of `GITHUB_REF` varies for a closed pull request depending on whether the pull request has been merged or not. If a pull request was closed but not merged, it will be `refs/pull/PULL_REQUEST_NUMBER/merge`. If a pull request was closed as a result of being merged, it will be the fully qualified `ref` of the branch it was merged into, for example `/refs/heads/main`.
 
 Runs your workflow when activity on a pull request in the workflow's repository occurs. For example, if no activity types are specified, the workflow runs when a pull request is opened or reopened or when the head branch of the pull request is updated. For activity related to pull request reviews, pull request review comments, or pull request comments, use the [`pull_request_review`](#pull_request_review), [`pull_request_review_comment`](#pull_request_review_comment), or [`issue_comment`](#issue_comment) events instead. For information about the pull request APIs, see [AUTOTITLE](/graphql/reference/objects#pullrequest) in the GraphQL API documentation or [AUTOTITLE](/rest/pulls).

data/features/actions-github-token-pull-request-approval.yml

@@ -0,0 +1,7 @@
+# Approval-required workflow runs for pull requests created or updated by
+# workflows using GITHUB_TOKEN. Implementation feature flag:
+# `actions_requires_approval_for_actions_bot_prs`.
+versions:
+  fpt: '*'
+  ghec: '*'
+  # ghes: '>=3.XX' # Uncomment when this ships to GHES (currently rolling out on dotcom)

data/reusables/actions/actions-do-not-trigger-workflows.md

@@ -1 +1,6 @@
-When you use the repository's `GITHUB_TOKEN` to perform tasks, events triggered by the `GITHUB_TOKEN`, with the exception of `workflow_dispatch` and `repository_dispatch`, will not create a new workflow run. This prevents you from accidentally creating recursive workflow runs. For example, if a workflow run pushes code using the repository's `GITHUB_TOKEN`, a new workflow will not run even when the repository contains a workflow configured to run when `push` events occur.
+When you use the repository's `GITHUB_TOKEN` to perform tasks, events triggered by the `GITHUB_TOKEN` will not create a new workflow run, with the following exceptions:
+
+* `workflow_dispatch` and `repository_dispatch` events always create workflow runs.{% ifversion actions-github-token-pull-request-approval %}
+* `pull_request` events with the `opened`, `synchronize`, or `reopened` activity types: when a workflow using `GITHUB_TOKEN` creates or updates a pull request, the resulting `pull_request` event creates workflow runs in an **approval-required** state. The pull request displays a banner in the merge box, and a user with write access to the repository can start the runs by selecting **Approve workflows to run**. Other `pull_request` activity types (such as `labeled`, `edited`, or `closed`) do not create workflow runs. This prevents recursive workflow runs while still allowing CI workflows to run on pull requests created by automation. For more information about approving workflow runs, see [AUTOTITLE](/actions/how-tos/manage-workflow-runs/approve-runs-from-forks).{% endif %}
+
+For all other events, this behavior prevents you from accidentally creating recursive workflow runs. For example, if a workflow run pushes code using the repository's `GITHUB_TOKEN`, a new workflow will not run even when the repository contains a workflow configured to run when `push` events occur.