Merge d03156b5b87293bfcac690d17511cb25c89bd3af into 3b9b8c884f6b4bb4d5be2779c26374abadae0871

Add a scenario where it is necessary to push a commit to a pull request.

README.md

@@ -33,6 +33,9 @@ Please refer to the [release page](https://github.com/actions/checkout/releases/
     # with the local git config, which enables your scripts to run authenticated git
     # commands. The post-job step removes the PAT.
     #
+    # If any of the submodules are private GitHub repos, pass in a PAT with read-access 
+    # to them. 
+    #
     # We recommend using a service account with the least permissions necessary. Also
     # when generating a new PAT, select the least scopes necessary.
     #
@@ -110,8 +113,8 @@ Please refer to the [release page](https://github.com/actions/checkout/releases/
     # Whether to checkout submodules: `true` to checkout submodules or `recursive` to
     # recursively checkout submodules.
     #
-    # When the `ssh-key` input is not provided, SSH URLs beginning with
-    # `git@github.com:` are converted to HTTPS.
+    # When neither the `ssh-key` nor the `token` inputs are provided, SSH URLs 
+    # beginning with `git@github.com:` are converted to HTTPS. 
     #
     # Default: false
     submodules: ''
@@ -143,6 +146,7 @@ Please refer to the [release page](https://github.com/actions/checkout/releases/
 - [Checkout pull request HEAD commit instead of merge commit](#Checkout-pull-request-HEAD-commit-instead-of-merge-commit)
 - [Checkout pull request on closed event](#Checkout-pull-request-on-closed-event)
 - [Push a commit using the built-in token](#Push-a-commit-using-the-built-in-token)
+- [Push a commit to a PR using the built-in token](#Push-a-commit-to-a-PR-using-the-built-in-token)
 
 ## Fetch only the root files
 
@@ -239,12 +243,19 @@ Please refer to the [release page](https://github.com/actions/checkout/releases/
   uses: actions/checkout@v4
   with:
     repository: my-org/my-private-tools
-    token: ${{ secrets.GH_PAT }} # `GH_PAT` is a secret that contains your PAT
+    token: ${{ secrets.GH_PAT }}  # `GH_PAT` is a secret that contains a PAT with read-access to this private repository
     path: my-tools
 ```
 
-> - `${{ github.token }}` is scoped to the current repository, so if you want to checkout a different repository that is private you will need to provide your own [PAT](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line).
+## Checkout a repo and its private submodules
 
+```yaml
+- name: Checkout
+  uses: actions/checkout@v2
+  with:
+    submodules: true
+    token: ${{ secrets.GH_PAT }} # `GH_PAT` is a secret that contains a PAT with read-access to the private submodules
+```
 
 ## Checkout pull request HEAD commit instead of merge commit
 
@@ -288,6 +299,31 @@ jobs:
 ```
 *NOTE:* The user email is `{user.id}+{user.login}@users.noreply.github.com`. See users API: https://api.github.com/users/github-actions%5Bbot%5D
 
+## Push a commit to a PR using the built-in token
+
+In a pull request trigger, `ref` is required as GitHub Actions checks out in detached HEAD mode, meaning it doesn’t check out your branch by default.
+
+```yaml
+on: pull_request
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.head_ref }}
+      - run: |
+          date > generated.txt
+          # Note: the following account information will not work on GHES
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add .
+          git commit -m "generated"
+          git push
+```
+*NOTE:* The user email is `{user.id}+{user.login}@users.noreply.github.com`. See users API: https://api.github.com/users/github-actions%5Bbot%5D
+
+
 # License
 
 The scripts and documentation in this project are released under the [MIT License](LICENSE)