- [Fixed an issue where checkout failed to run in container jobs due to the new git setting `safe.directory`](https://github.com/actions/checkout/pull/762)
- [Fixed an issue where checkout failed to run in container jobs due to the new git setting `safe.directory`](https://github.com/actions/checkout/pull/762)
- [Bumped various npm package versions](https://github.com/actions/checkout/pull/744)
- [Bumped various npm package versions](https://github.com/actions/checkout/pull/744)
@ -66,7 +69,6 @@
- Aligns better with container actions, where `github.workspace` gets mapped in
- Aligns better with container actions, where `github.workspace` gets mapped in
- Removed input `submodules`
- Removed input `submodules`
## v1
## v1
Refer [here](https://github.com/actions/checkout/blob/v1/CHANGELOG.md) for the V1 changelog
Refer [here](https://github.com/actions/checkout/blob/v1/CHANGELOG.md) for the V1 changelog
@ -18,6 +18,7 @@ When Git 2.18 or higher is not in your PATH, falls back to the REST API to downl
# Usage
# Usage
<!-- start usage -->
<!-- start usage -->
```yaml
```yaml
- uses: actions/checkout@v3
- uses: actions/checkout@v3
with:
with:
@ -102,6 +103,7 @@ When Git 2.18 or higher is not in your PATH, falls back to the REST API to downl
# https://my-ghes-server.example.com
# https://my-ghes-server.example.com
github-server-url: ''
github-server-url: ''
```
```
<!-- end usage -->
<!-- end usage -->
# Scenarios
# Scenarios
@ -187,7 +189,6 @@ When Git 2.18 or higher is not in your PATH, falls back to the REST API to downl
> - `${{ 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).
> - `${{ 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 pull request HEAD commit instead of merge commit
## Checkout pull request HEAD commit instead of merge commit
@ -17,76 +17,77 @@ We want to take this opportunity to make behavioral changes, from v1. This docum
### Inputs
### Inputs
```yaml
```yaml
repository:
repository:
description: 'Repository name with owner. For example, actions/checkout'
description: 'Repository name with owner. For example, actions/checkout'
default: ${{ github.repository }}
default: ${{ github.repository }}
ref:
ref:
description: >
description: >
The branch, tag or SHA to checkout. When checking out the repository that
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
triggered a workflow, this defaults to the reference or SHA for that
event. Otherwise, uses the default branch.
event. Otherwise, uses the default branch.
token:
token:
description: >
description: >
Personal access token (PAT) used to fetch the repository. The PAT is configured
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
with the local git config, which enables your scripts to run authenticated git
commands. The post-job step removes the PAT.
commands. The post-job step removes the PAT.
We recommend using a service account with the least permissions necessary.
We recommend using a service account with the least permissions necessary.
Also when generating a new PAT, select the least scopes 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)
[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 }}
default: ${{ github.token }}
ssh-key:
ssh-key:
description: >
description: >
SSH key used to fetch the repository. The SSH key is configured with the local
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.
git config, which enables your scripts to run authenticated git commands.
The post-job step removes the SSH key.
The post-job step removes the SSH key.
We recommend using a service account with the least permissions necessary.
We recommend using a service account with the least permissions necessary.
Known hosts in addition to the user and global host key database. The public
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 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-keyscan github.com`. The public key for github.com is always implicitly added.
ssh-strict:
ssh-strict:
description: >
description: >
Whether to perform strict host key checking. When true, adds the options `StrictHostKeyChecking=yes`
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
and `CheckHostIP=no` to the SSH command line. Use the input `ssh-known-hosts` to
configure additional hosts.
configure additional hosts.
default: true
default: true
persist-credentials:
persist-credentials:
description: 'Whether to configure the token or SSH key with the local git config'
description: 'Whether to configure the token or SSH key with the local git config'
default: true
default: true
path:
path:
description: 'Relative path under $GITHUB_WORKSPACE to place the repository'
description: 'Relative path under $GITHUB_WORKSPACE to place the repository'
clean:
clean:
description: 'Whether to execute `git clean -ffdx && git reset --hard HEAD` before fetching'
description: 'Whether to execute `git clean -ffdx && git reset --hard HEAD` before fetching'
default: true
default: true
fetch-depth:
fetch-depth:
description: 'Number of commits to fetch. 0 indicates all history for all tags and branches.'
description: 'Number of commits to fetch. 0 indicates all history for all tags and branches.'
default: 1
default: 1
lfs:
lfs:
description: 'Whether to download Git-LFS files'
description: 'Whether to download Git-LFS files'
default: false
default: false
submodules:
submodules:
description: >
description: >
Whether to checkout submodules: `true` to checkout submodules or `recursive` to
Whether to checkout submodules: `true` to checkout submodules or `recursive` to
recursively checkout submodules.
recursively checkout submodules.
When the `ssh-key` input is not provided, SSH URLs beginning with `git@github.com:` are
When the `ssh-key` input is not provided, SSH URLs beginning with `git@github.com:` are
converted to HTTPS.
converted to HTTPS.
default: false
default: false
```
```
Note:
Note:
- SSH support is new
- SSH support is new
- `persist-credentials` is new
- `persist-credentials` is new
- `path` behavior is different (refer [below](#path) for details)
- `path` behavior is different (refer [below](#path) for details)
@ -96,6 +97,7 @@ Note:
When a sufficient version of git is not in the PATH, fallback to the [web API](https://developer.github.com/v3/repos/contents/#get-archive-link) to download a tarball/zipball.
When a sufficient version of git is not in the PATH, fallback to the [web API](https://developer.github.com/v3/repos/contents/#get-archive-link) to download a tarball/zipball.
Note:
Note:
- LFS files are not included in the archive. Therefore fail if LFS is set to true.
- LFS files are not included in the archive. Therefore fail if LFS is set to true.
- Submodules are also not included in the archive.
- Submodules are also not included in the archive.
@ -108,6 +110,7 @@ A post script will remove the credentials (cleanup for self-hosted).
Users may opt-out by specifying `persist-credentials: false`
Users may opt-out by specifying `persist-credentials: false`
Note:
Note:
- Users scripting `git commit` may need to set the username and email. The service does not provide any reasonable default value. Users can add `git config user.name <NAME>` and `git config user.email <EMAIL>`. We will document this guidance.
- Users scripting `git commit` may need to set the username and email. The service does not provide any reasonable default value. Users can add `git config user.name <NAME>` and `git config user.email <EMAIL>`. We will document this guidance.
#### PAT
#### PAT
@ -115,6 +118,7 @@ Note:
When using the `${{github.token}}` or a PAT, the token will be persisted in the local git config. The config key `http.https://github.com/.extraheader` enables an auth header to be specified on all authenticated commands `AUTHORIZATION: basic <BASE64_U:P>`.
When using the `${{github.token}}` or a PAT, the token will be persisted in the local git config. The config key `http.https://github.com/.extraheader` enables an auth header to be specified on all authenticated commands `AUTHORIZATION: basic <BASE64_U:P>`.
Note:
Note:
- The auth header is scoped to all of github `http.https://github.com/.extraheader`
- The auth header is scoped to all of github `http.https://github.com/.extraheader`
- Additional public remotes also just work.
- Additional public remotes also just work.
- If users want to authenticate to an additional private remote, they should provide the `token` input.
- If users want to authenticate to an additional private remote, they should provide the `token` input.
When the input `ssh-strict` is set to `false`, the options `CheckHostIP` and `StrictHostKeyChecking` will not be overridden.
When the input `ssh-strict` is set to `false`, the options `CheckHostIP` and `StrictHostKeyChecking` will not be overridden.
Note:
Note:
- When `ssh-strict` is set to `true` (default), the SSH option `CheckHostIP` can safely be disabled.
- When `ssh-strict` is set to `true` (default), the SSH option `CheckHostIP` can safely be disabled.
Strict host checking verifies the server's public key. Therefore, IP verification is unnecessary
Strict host checking verifies the server's public key. Therefore, IP verification is unnecessary
and noisy. For example:
and noisy. For example:
@ -158,6 +163,7 @@ If a SHA isn't available (e.g. multi repo), then fetch only the specified ref wi
The input `fetch-depth` can be used to control the depth.
The input `fetch-depth` can be used to control the depth.
Note:
Note:
- Fetching a single commit is supported by Git wire protocol version 2. The git client uses protocol version 0 by default. The desired protocol version can be overridden in the git config or on the fetch command line invocation (`-c protocol.version=2`). We will override on the fetch command line, for transparency.
- Fetching a single commit is supported by Git wire protocol version 2. The git client uses protocol version 0 by default. The desired protocol version can be overridden in the git config or on the fetch command line invocation (`-c protocol.version=2`). We will override on the fetch command line, for transparency.
- Git client version 2.18+ (released June 2018) is required for wire protocol version 2.
- Git client version 2.18+ (released June 2018) is required for wire protocol version 2.
@ -168,6 +174,7 @@ For CI, checkout will create a local ref with the upstream set. This allows user
For PR, continue to checkout detached head. The PR branch is special - the branch and merge commit are created by the server. It doesn't match a users' local workflow.
For PR, continue to checkout detached head. The PR branch is special - the branch and merge commit are created by the server. It doesn't match a users' local workflow.
Note:
Note:
- Consider deleting all local refs during cleanup if that helps avoid collisions. More testing required.
- Consider deleting all local refs during cleanup if that helps avoid collisions. More testing required.
### Path
### Path
@ -192,6 +199,7 @@ These behavioral changes align better with container actions. The [documented fi
- `/github/workflow`
- `/github/workflow`
Note:
Note:
- The tracking config will not be updated to reflect the path of the workflow repo.
- The tracking config will not be updated to reflect the path of the workflow repo.
- Any existing workflow repo will not be moved when the checkout path changes. In fact some customers want to checkout the workflow repo twice, side by side against different branches.
- Any existing workflow repo will not be moved when the checkout path changes. In fact some customers want to checkout the workflow repo twice, side by side against different branches.
- Actions that need to operate only against the root of the self repo, should expose a `path` input.
- Actions that need to operate only against the root of the self repo, should expose a `path` input.
@ -205,6 +213,7 @@ This default fits the mainline scenario well: single checkout
For multi-checkout, users must specify the `path` input for at least one of the repositories.
For multi-checkout, users must specify the `path` input for at least one of the repositories.
Note:
Note:
- An alternative is for the self repo to default to `./` and other repos default to `<REPO_NAME>`. However nested layout is an atypical git layout and therefore is not a good default. Users should supply the path info.
- An alternative is for the self repo to default to `./` and other repos default to `<REPO_NAME>`. However nested layout is an atypical git layout and therefore is not a good default. Users should supply the path info.
#### Example - Nested layout
#### Example - Nested layout
@ -265,6 +274,7 @@ Credentials will be persisted in the submodules local git config too.
### Port to typescript
### Port to typescript
The checkout action should be a typescript action on the GitHub graph, for the following reasons:
The checkout action should be a typescript action on the GitHub graph, for the following reasons:
- Enables customers to fork the checkout repo and modify
- Enables customers to fork the checkout repo and modify
- Serves as an example for customers
- Serves as an example for customers
- Demystifies the checkout action manifest
- Demystifies the checkout action manifest
@ -272,6 +282,7 @@ The checkout action should be a typescript action on the GitHub graph, for the f
- Reduce the amount of runner code to port (if we ever do)
- Reduce the amount of runner code to port (if we ever do)
Note:
Note:
- This means job-container images will need git in the PATH, for checkout.
- This means job-container images will need git in the PATH, for checkout.