Merge 0865c4bfce7deea86ea9a5aebef018b997ab2a29 into 3b9b8c884f6b4bb4d5be2779c26374abadae0871

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

README.md

@@ -29,6 +29,11 @@ Please refer to the [release page](https://github.com/actions/checkout/releases/
     # Otherwise, uses the default branch.
     ref: ''
 
+    # The commit SHA to checkout. Used when ref is not specified or is ambiguous. This
+    # can be used as a replacement for ref, or alongside it to checkout a specific
+    # commit of the ref.
+    commit: ''
+
     # Personal access token (PAT) used to fetch the repository. The PAT is configured
     # with the local git config, which enables your scripts to run authenticated git
     # commands. The post-job step removes the PAT.
@@ -143,6 +148,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
 
@@ -288,6 +294,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)

__test__/input-helper.test.ts

@@ -144,4 +144,30 @@ describe('input-helper tests', () => {
     const settings: IGitSourceSettings = await inputHelper.getInputs()
     expect(settings.workflowOrganizationId).toBe(123456)
   })
+
+  it('accepts ref and commit', async () => {
+    inputs.ref = 'refs/pull/123/merge'
+    inputs.commit = '0123456789012345678901234567890123456789'
+    const settings: IGitSourceSettings = await inputHelper.getInputs()
+    expect(settings).toBeTruthy()
+    expect(settings.ref).toBeTruthy()
+    expect(settings.ref).toStrictEqual('refs/pull/123/merge')
+    expect(settings.commit).toBeTruthy()
+    expect(settings.commit).toStrictEqual(
+      '0123456789012345678901234567890123456789'
+    )
+  })
+
+  it('ref fallbacks to commit if ref is empty but commit is specified', async () => {
+    inputs.ref = ''
+    inputs.commit = '0123456789012345678901234567890123456789'
+    const settings: IGitSourceSettings = await inputHelper.getInputs()
+    expect(settings).toBeTruthy()
+    expect(settings.ref).toBeFalsy()
+    expect(settings.ref).toStrictEqual('')
+    expect(settings.commit).toBeTruthy()
+    expect(settings.commit).toStrictEqual(
+      '0123456789012345678901234567890123456789'
+    )
+  })
 })

action.yml

@@ -9,6 +9,11 @@ inputs:
       The branch, tag or SHA to checkout. When checking out the repository that
       triggered a workflow, this defaults to the reference or SHA for that
       event.  Otherwise, uses the default branch.
+  commit:
+    description: >
+      The commit SHA to checkout. Used when ref is not specified or is ambiguous.
+      This can be used as a replacement for ref, or alongside it to checkout a
+      specific commit of the ref.
   token:
     description: >
       Personal access token (PAT) used to fetch the repository. The PAT is configured

dist/index.js

@@ -1744,7 +1744,11 @@ function getInputs() {
         const isWorkflowRepository = qualifiedRepository.toUpperCase() ===
             `${github.context.repo.owner}/${github.context.repo.repo}`.toUpperCase();
         // Source branch, source version
-        result.ref = core.getInput('ref');
+        result.commit = core.getInput('commit');
+        if (result.commit && !result.commit.match(/^[0-9a-fA-F]{40}$/)) {
+            throw new Error(`The commit SHA '${result.commit}' is not a valid SHA.`);
+        }
+        result.ref = core.getInput('ref') || result.commit;
         if (!result.ref) {
             if (isWorkflowRepository) {
                 result.ref = github.context.ref;

src/input-helper.ts

@@ -57,7 +57,12 @@ export async function getInputs(): Promise<IGitSourceSettings> {
     `${github.context.repo.owner}/${github.context.repo.repo}`.toUpperCase()
 
   // Source branch, source version
-  result.ref = core.getInput('ref')
+  result.commit = core.getInput('commit')
+  if (result.commit && !result.commit.match(/^[0-9a-fA-F]{40}$/)) {
+    throw new Error(`The commit SHA '${result.commit}' is not a valid SHA.`)
+  }
+
+  result.ref = core.getInput('ref') || result.commit
   if (!result.ref) {
     if (isWorkflowRepository) {
       result.ref = github.context.ref