Merge f80349a6ad into 85e6279cec

* Update README.md

* Update README.md

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

---------

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

.github/workflows/test.yml

@@ -29,6 +29,8 @@ jobs:
         run: __test__/verify-no-unstaged-changes.sh
 
   test:
+    env:
+      main_path: main_path_test
     strategy:
       matrix:
         runs-on: [ubuntu-latest, macos-latest, windows-latest]
@@ -62,6 +64,16 @@ jobs:
         shell: bash
         run: __test__/verify-clean.sh
 
+      # Use environment variable as path
+      - name: Environment path test
+        uses: ./
+        with:
+          ref: test-data/v2/basic
+          path: ${{ env.main_path }}
+      - name: Verify environment path test
+        shell: bash
+        run: __test__/verify-environment-path.sh
+
       # Side by side
       - name: Checkout side by side 1
         uses: ./

README.md

@@ -71,7 +71,7 @@ Please refer to the [release page](https://github.com/actions/checkout/releases/
     # Default: true
     persist-credentials: ''
 
-    # Relative path under $GITHUB_WORKSPACE to place the repository
+    # Relative or absolute path under $GITHUB_WORKSPACE to place the repository
     path: ''
 
     # Whether to execute `git clean -ffdx && git reset --hard HEAD` before fetching
@@ -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,19 @@ 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 repo with a environment based path
+
+```yaml
+env:
+  main_path: ${{ github.workspace }}/main
+steps:
+- name: Checkout
+  uses: actions/checkout@v2
+  with:
+    path: ${{ env.main_path }}
+```
 
 ## Checkout multiple repos (nested)
 
@@ -225,7 +238,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)
 
@@ -288,6 +301,40 @@ 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
+
+# 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)

__test__/verify-environment-path.sh

@@ -0,0 +1,6 @@
+#!/bin/bash
+
+if [ ! -f "./main_path_test/basic-file.txt" ]; then
+    echo "Expected file does not exist"
+    exit 1
+fi

action.yml

@@ -53,7 +53,7 @@ inputs:
     description: 'Whether to configure the token or SSH key with the local git config'
     default: true
   path:
-    description: 'Relative path under $GITHUB_WORKSPACE to place the repository'
+    description: 'Relative or absolute path under $GITHUB_WORKSPACE to place the repository'
   clean:
     description: 'Whether to execute `git clean -ffdx && git reset --hard HEAD` before fetching'
     default: true

adrs/0153-checkout-v2.md

@@ -65,7 +65,7 @@ We want to take this opportunity to make behavioral changes, from v1. This docum
     description: 'Whether to configure the token or SSH key with the local git config'
     default: true
   path:
-    description: 'Relative path under $GITHUB_WORKSPACE to place the repository'
+    description: 'Relative or absolute path under $GITHUB_WORKSPACE to place the repository'
   clean:
     description: 'Whether to execute `git clean -ffdx && git reset --hard HEAD` before fetching'
     default: true