Merge f3b199b7ed into 85e6279cec

* Update README.md

* Update README.md

Co-authored-by: Josh Gross <joshmgross@github.com>

---------

Co-authored-by: Josh Gross <joshmgross@github.com>

README.md

@@ -143,6 +143,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
 
@@ -211,7 +212,7 @@ Please refer to the [release page](https://github.com/actions/checkout/releases/
     repository: my-org/my-tools
     path: my-tools
 ```
-> - If your secondary repository is private you will need to add the option noted in [Checkout multiple repos (private)](#Checkout-multiple-repos-private)
+> - If your secondary repository is private or internal you will need to add the option noted in [Checkout multiple repos (private)](#Checkout-multiple-repos-private)
 
 ## Checkout multiple repos (nested)
 
@@ -225,7 +226,7 @@ Please refer to the [release page](https://github.com/actions/checkout/releases/
     repository: my-org/my-tools
     path: my-tools
 ```
-> - If your secondary repository is private you will need to add the option noted in [Checkout multiple repos (private)](#Checkout-multiple-repos-private)
+> - If your secondary repository is private or internal you will need to add the option noted in [Checkout multiple repos (private)](#Checkout-multiple-repos-private)
 
 ## Checkout multiple repos (private)
 
@@ -280,14 +281,44 @@ jobs:
       - 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
 
+## 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 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
+
+# Recommended permissions
+
+When using the `checkout` action in your GitHub Actions workflow, it is recommended to set the following `GITHUB_TOKEN` permissions to ensure proper functionality, unless alternative auth is provided via the `token` or `ssh-key` inputs:
+
+```yaml
+permissions:
+  contents: read
+```
+
 # License
 
 The scripts and documentation in this project are released under the [MIT License](LICENSE)

action.yml

@@ -22,6 +22,12 @@ inputs:
 
       [Learn more about creating and using encrypted secrets](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets)
     default: ${{ github.token }}
+  configure-user:
+    description: >
+      Whether to configure user.name and user.email in the local git config.
+      This is required to push a commit from a Github Action Workflow.
+      Set to `false` to disable the config.
+    default: true
   ssh-key:
     description: >
       SSH key used to fetch the repository. The SSH key is configured with the local

dist/index.js

@@ -1813,6 +1813,9 @@ function getInputs() {
         core.debug(`recursive submodules = ${result.nestedSubmodules}`);
         // Auth token
         result.authToken = core.getInput('token', { required: true });
+        // Configure user
+        result.configureUser = 
+            (core.getInput('configure-user') || 'true').toUpperCase() === 'TRUE'
         // SSH
         result.sshKey = core.getInput('ssh-key');
         result.sshKnownHosts = core.getInput('ssh-known-hosts');

src/git-source-provider.ts

@@ -274,6 +274,14 @@ export async function getSource(settings: IGitSourceSettings): Promise<void> {
       settings.commit,
       settings.githubServerUrl
     )
+    if (settings.configureUser) {
+      if (!await git.configExists('user.name', true)) {
+        await git.config('user.name', 'github-action[bot]', true)
+      }
+      if (!await git.configExists('user.email', true)) {
+        await git.config('user.email', '41898282+github-actions[bot]@users.noreply.github.com', true)
+      } 
+    }
   } finally {
     // Remove auth
     if (authHelper) {

src/git-source-settings.ts

@@ -79,6 +79,11 @@ export interface IGitSourceSettings {
    */
   authToken: string
 
+  /**
+   * Indicates whether to set a default user name and email in the local git config
+   */
+  configureUser: boolean
+
   /**
    * The SSH key to configure
    */

src/input-helper.ts

@@ -138,6 +138,10 @@ export async function getInputs(): Promise<IGitSourceSettings> {
   // Auth token
   result.authToken = core.getInput('token', {required: true})
 
+  // Configure user
+  result.configureUser = 
+    (core.getInput('configure-user') || 'true').toUpperCase() === 'TRUE'
+
   // SSH
   result.sshKey = core.getInput('ssh-key')
   result.sshKnownHosts = core.getInput('ssh-known-hosts')