diff --git a/README.md b/README.md
index 64dc025..8ff8967 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,5 @@
+
+
[](https://github.com/actions/checkout/actions/workflows/test.yml)
# Checkout V4
@@ -326,3 +328,656 @@ permissions:
# License
The scripts and documentation in this project are released under the [MIT License](LICENSE)
+Skip to content
+Navigation Menu
+actions
+checkout
+
+Code
+Issues
+486
+Pull requests
+100
+Discussions
+Actions
+Security
+Insights
+checkout
+/README.md
+Go to file
+t
+joshmgross
+joshmgross
+Adjust positioning of user email note and permissions heading (#2044)
+85e6279
+ ·
+3 months ago
+328 lines (260 loc) · 10.4 KB ·
+
+Preview
+
+Code
+
+Blame
+[](https://github.com/actions/checkout/actions/workflows/test.yml)
+
+# Checkout V4
+
+This action checks-out your repository under `$GITHUB_WORKSPACE`, so your workflow can access it.
+
+Only a single commit is fetched by default, for the ref/SHA that triggered the workflow. Set `fetch-depth: 0` to fetch all history for all branches and tags. Refer [here](https://docs.github.com/actions/using-workflows/events-that-trigger-workflows) to learn which commit `$GITHUB_SHA` points to for different events.
+
+The auth token is persisted in the local git config. This enables your scripts to run authenticated git commands. The token is removed during post-job cleanup. Set `persist-credentials: false` to opt-out.
+
+When Git 2.18 or higher is not in your PATH, falls back to the REST API to download the files.
+
+# What's new
+
+Please refer to the [release page](https://github.com/actions/checkout/releases/latest) for the latest release notes.
+
+# Usage
+
+<!-- start usage -->
+```yaml
+- uses: actions/checkout@v4
+ with:
+ # Repository name with owner. For example, actions/checkout
+ # Default: ${{ github.repository }}
+ repository: ''
+
+ # 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.
+ ref: ''
+
+ # 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.
+ #
+ # We recommend using a service account with the least permissions necessary. Also
+ # when generating a new PAT, select the least scopes necessary.
+ #
+ # [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 }}
+ token: ''
+
+ # SSH key used to fetch the repository. The SSH key is configured with the local
+ # git config, which enables your scripts to run authenticated git commands. The
+ # post-job step removes the SSH key.
+ #
+ # We recommend using a service account with the least permissions necessary.
+ #
+ # [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)
+ ssh-key: ''
+
+ # Known hosts in addition to the user and global host key database. The public SSH
+ # keys for a host may be obtained using the utility `ssh-keyscan`. For example,
+ # `ssh-keyscan github.com`. The public key for github.com is always implicitly
+ # added.
+ ssh-known-hosts: ''
+
+ # Whether to perform strict host key checking. When true, adds the options
+ # `StrictHostKeyChecking=yes` and `CheckHostIP=no` to the SSH command line. Use
+ # the input `ssh-known-hosts` to configure additional hosts.
+ # Default: true
+ ssh-strict: ''
+
+ # The user to use when connecting to the remote SSH host. By default 'git' is
+ # used.
+ # Default: git
+ ssh-user: ''
+
+ # Whether to configure the token or SSH key with the local git config
+ # Default: true
+ persist-credentials: ''
+
+ # Relative path under $GITHUB_WORKSPACE to place the repository
+ path: ''
+
+ # Whether to execute `git clean -ffdx && git reset --hard HEAD` before fetching
+ # Default: true
+ clean: ''
+
+ # Partially clone against a given filter. Overrides sparse-checkout if set.
+ # Default: null
+ filter: ''
+
+ # Do a sparse checkout on given patterns. Each pattern should be separated with
+ # new lines.
+ # Default: null
+ sparse-checkout: ''
+
+ # Specifies whether to use cone-mode when doing a sparse checkout.
+ # Default: true
+ sparse-checkout-cone-mode: ''
+
+ # Number of commits to fetch. 0 indicates all history for all branches and tags.
+ # Default: 1
+ fetch-depth: ''
+
+ # Whether to fetch tags, even if fetch-depth > 0.
+ # Default: false
+ fetch-tags: ''
+
+ # Whether to show progress status output when fetching.
+ # Default: true
+ show-progress: ''
+
+ # Whether to download Git-LFS files
+ # Default: false
+ lfs: ''
+
+ # 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.
+ #
+ # Default: false
+ submodules: ''
+
+ # Add repository path as safe.directory for Git global config by running `git
+ # config --global --add safe.directory <path>`
+ # Default: true
+ set-safe-directory: ''
+
+ # The base URL for the GitHub instance that you are trying to clone from, will use
+ # environment defaults to fetch from the same instance that the workflow is
+ # running from unless specified. Example URLs are https://github.com or
+ # https://my-ghes-server.example.com
+ github-server-url: ''
+```
+<!-- end usage -->
+
+# Scenarios
+
+- [Fetch only the root files](#Fetch-only-the-root-files)
+- [Fetch only the root files and `.github` and `src` folder](#Fetch-only-the-root-files-and-github-and-src-folder)
+- [Fetch only a single file](#Fetch-only-a-single-file)
+- [Fetch all history for all tags and branches](#Fetch-all-history-for-all-tags-and-branches)
+- [Checkout a different branch](#Checkout-a-different-branch)
+- [Checkout HEAD^](#Checkout-HEAD)
+- [Checkout multiple repos (side by side)](#Checkout-multiple-repos-side-by-side)
+- [Checkout multiple repos (nested)](#Checkout-multiple-repos-nested)
+- [Checkout multiple repos (private)](#Checkout-multiple-repos-private)
+- [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
+
+```yaml
+- uses: actions/checkout@v4
+ with:
+ sparse-checkout: .
+```
+
+## Fetch only the root files and `.github` and `src` folder
+
+```yaml
+- uses: actions/checkout@v4
+ with:
+ sparse-checkout: |
+ .github
+ src
+```
+
+## Fetch only a single file
+ ref: ${{ github.event.pull_request.head.sha }}
+```
+
+## Checkout pull request on closed event
+
+```yaml
+on:
+ pull_request:
+ branches: [main]
+ types: [opened, synchronize, closed]
+jobs:
+ build:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+```
+
+## Push a commit using the built-in token
+
+```yaml
+on: push
+jobs:
+ build:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - 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 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)
+checkout/README.md at main · actions/checkout
+
+Skip to content
+Navigation Menu
+actions
+checkout
+
+Code
+Issues
+486
+Pull requests
+100
+Discussions
+Actions
+Security
+Insights
+checkout
+/README.md
+Go to file
+t
+joshmgross
+joshmgross
+Adjust positioning of user email note and permissions heading (#2044)
+85e6279
+ ·
+3 months ago
+328 lines (260 loc) · 10.4 KB ·
+
+Preview
+
+Code
+
+Blame
+[](https://github.com/actions/checkout/actions/workflows/test.yml)
+
+# Checkout V4
+
+This action checks-out your repository under `$GITHUB_WORKSPACE`, so your workflow can access it.
+
+Only a single commit is fetched by default, for the ref/SHA that triggered the workflow. Set `fetch-depth: 0` to fetch all history for all branches and tags. Refer [here](https://docs.github.com/actions/using-workflows/events-that-trigger-workflows) to learn which commit `$GITHUB_SHA` points to for different events.
+
+The auth token is persisted in the local git config. This enables your scripts to run authenticated git commands. The token is removed during post-job cleanup. Set `persist-credentials: false` to opt-out.
+
+When Git 2.18 or higher is not in your PATH, falls back to the REST API to download the files.
+
+# What's new
+
+Please refer to the [release page](https://github.com/actions/checkout/releases/latest) for the latest release notes.
+
+# Usage
+
+<!-- start usage -->
+```yaml
+- uses: actions/checkout@v4
+ with:
+ # Repository name with owner. For example, actions/checkout
+ # Default: ${{ github.repository }}
+ repository: ''
+
+ # 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.
+ ref: ''
+
+ # 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.
+ #
+ # We recommend using a service account with the least permissions necessary. Also
+ # when generating a new PAT, select the least scopes necessary.
+ #
+ # [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 }}
+ token: ''
+
+ # SSH key used to fetch the repository. The SSH key is configured with the local
+ # git config, which enables your scripts to run authenticated git commands. The
+ # post-job step removes the SSH key.
+ #
+ # We recommend using a service account with the least permissions necessary.
+ #
+ # [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)
+ ssh-key: ''
+
+ # Known hosts in addition to the user and global host key database. The public SSH
+ # keys for a host may be obtained using the utility `ssh-keyscan`. For example,
+ # `ssh-keyscan github.com`. The public key for github.com is always implicitly
+ # added.
+ ssh-known-hosts: ''
+
+ # Whether to perform strict host key checking. When true, adds the options
+ # `StrictHostKeyChecking=yes` and `CheckHostIP=no` to the SSH command line. Use
+ # the input `ssh-known-hosts` to configure additional hosts.
+ # Default: true
+ ssh-strict: ''
+
+ # The user to use when connecting to the remote SSH host. By default 'git' is
+ # used.
+ # Default: git
+ ssh-user: ''
+
+ # Whether to configure the token or SSH key with the local git config
+ # Default: true
+ persist-credentials: ''
+
+ # Relative path under $GITHUB_WORKSPACE to place the repository
+ path: ''
+
+ # Whether to execute `git clean -ffdx && git reset --hard HEAD` before fetching
+ # Default: true
+ clean: ''
+
+ # Partially clone against a given filter. Overrides sparse-checkout if set.
+ # Default: null
+ filter: ''
+
+ # Do a sparse checkout on given patterns. Each pattern should be separated with
+ # new lines.
+ # Default: null
+ sparse-checkout: ''
+
+ # Specifies whether to use cone-mode when doing a sparse checkout.
+ # Default: true
+ sparse-checkout-cone-mode: ''
+
+ # Number of commits to fetch. 0 indicates all history for all branches and tags.
+ # Default: 1
+ fetch-depth: ''
+
+ # Whether to fetch tags, even if fetch-depth > 0.
+ # Default: false
+ fetch-tags: ''
+
+ # Whether to show progress status output when fetching.
+ # Default: true
+ show-progress: ''
+
+ # Whether to download Git-LFS files
+ # Default: false
+ lfs: ''
+
+ # 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.
+ #
+ # Default: false
+ submodules: ''
+
+ # Add repository path as safe.directory for Git global config by running `git
+ # config --global --add safe.directory <path>`
+ # Default: true
+ set-safe-directory: ''
+
+ # The base URL for the GitHub instance that you are trying to clone from, will use
+ # environment defaults to fetch from the same instance that the workflow is
+ # running from unless specified. Example URLs are https://github.com or
+ # https://my-ghes-server.example.com
+ github-server-url: ''
+```
+<!-- end usage -->
+
+# Scenarios
+
+- [Fetch only the root files](#Fetch-only-the-root-files)
+- [Fetch only the root files and `.github` and `src` folder](#Fetch-only-the-root-files-and-github-and-src-folder)
+- [Fetch only a single file](#Fetch-only-a-single-file)
+- [Fetch all history for all tags and branches](#Fetch-all-history-for-all-tags-and-branches)
+- [Checkout a different branch](#Checkout-a-different-branch)
+- [Checkout HEAD^](#Checkout-HEAD)
+- [Checkout multiple repos (side by side)](#Checkout-multiple-repos-side-by-side)
+- [Checkout multiple repos (nested)](#Checkout-multiple-repos-nested)
+- [Checkout multiple repos (private)](#Checkout-multiple-repos-private)
+- [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
+
+```yaml
+- uses: actions/checkout@v4
+ with:
+ sparse-checkout: .
+```
+
+## Fetch only the root files and `.github` and `src` folder
+
+```yaml
+- uses: actions/checkout@v4
+ with:
+ sparse-checkout: |
+ .github
+ src
+```
+
+ ref: ${{ github.event.pull_request.head.sha }}
+```
+
+## Checkout pull request on closed event
+
+```yaml
+on:
+ pull_request:
+ branches: [main]
+ types: [opened, synchronize, closed]
+jobs:
+ build:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+```
+
+## Push a commit using the built-in token
+
+```yaml
+on: push
+jobs:
+ build:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - 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 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)
+checkout/README.md at 85e6279cec87321a52edac9c87bce653a07cf6c2 · actions/checkout
+
+- uses: actions/checkout@v4
+ with:
+ # Repository name with owner. For example, actions/checkout
+ # Default: ${{ github.repository }}
+ repository: ''
+
+ # 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.
+ ref: ''
+
+ # 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.
+ #
+ # We recommend using a service account with the least permissions necessary. Also
+ # when generating a new PAT, select the least scopes necessary.
+ #
+ # [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 }}
+ token: ''
+
+ # SSH key used to fetch the repository. The SSH key is configured with the local
+ # git config, which enables your scripts to run authenticated git commands. The
+ # post-job step removes the SSH key.
+ #
+ # We recommend using a service account with the least permissions necessary.
+ #
+ # [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)
+ ssh-key: ''
+
+ # Known hosts in addition to the user and global host key database. The public SSH
+ # keys for a host may be obtained using the utility `ssh-keyscan`. For example,
+ # `ssh-keyscan github.com`. The public key for github.com is always implicitly
+ # added.
+ ssh-known-hosts: ''
+
+ # Whether to perform strict host key checking. When true, adds the options
+ # `StrictHostKeyChecking=yes` and `CheckHostIP=no` to the SSH command line. Use
+ # the input `ssh-known-hosts` to configure additional hosts.
+ # Default: true
+ ssh-strict: ''
+
+ # The user to use when connecting to the remote SSH host. By default 'git' is
+ # used.
+ # Default: git
+ ssh-user: ''
+
+ # Whether to configure the token or SSH key with the local git config
+ # Default: true
+ persist-credentials: ''
+
+ # Relative path under $GITHUB_WORKSPACE to place the repository
+ path: ''
+
+ # Whether to execute `git clean -ffdx && git reset --hard HEAD` before fetching
+ # Default: true
+ clean: ''
+
+ # Partially clone against a given filter. Overrides sparse-checkout if set.
+ # Default: null
+ filter: ''
+
+ # Do a sparse checkout on given patterns. Each pattern should be separated with
+ # new lines.
+ # Default: null
+ sparse-checkout: ''
+
+ # Specifies whether to use cone-mode when doing a sparse checkout.
+ # Default: true
+ sparse-checkout-cone-mode: ''
+
+ # Number of commits to fetch. 0 indicates all history for all branches and tags.
+ # Default: 1
+ fetch-depth: ''
+
+ # Whether to fetch tags, even if fetch-depth > 0.
+ # Default: false
+ fetch-tags: ''
+
+ # Whether to show progress status output when fetching.
+ # Default: true
+ show-progress: ''
+
+ # Whether to download Git-LFS files
+ # Default: false
+ lfs: ''
+
+ # 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.
+ #
+ # Default: false
+ submodules: ''
+
+ # Add repository path as safe.directory for Git global config by running `git
+ # config --global --add safe.directory <path>`
+ # Default: true
+ set-safe-directory: ''
+
+ # The base URL for the GitHub instance that you are trying to clone from, will use
+ # environment defaults to fetch from the same instance that the workflow is
+ # running from unless specified. Example URLs are https://github.com or
+ # https://git-github-cospaes.thecontested.com
+ github-server-url: 'github.com/nofications