2022-10-17 16:49:29 +03:00
[![Build and Test ](https://github.com/actions/checkout/actions/workflows/test.yml/badge.svg )](https://github.com/actions/checkout/actions/workflows/test.yml)
2019-10-25 17:52:59 +03:00
2023-09-05 16:21:52 +03:00
# Checkout V4
2019-07-23 22:32:03 +03:00
2019-12-03 18:28:59 +03:00
This action checks-out your repository under `$GITHUB_WORKSPACE` , so your workflow can access it.
2019-07-23 22:32:03 +03:00
2023-10-13 18:07:47 +03:00
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.
2019-08-13 17:53:03 +03:00
2020-01-02 23:40:10 +03:00
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.
2019-07-23 22:32:03 +03:00
2019-12-06 06:10:31 +03:00
# What's new
2023-10-17 18:52:30 +03:00
Please refer to the [release page ](https://github.com/actions/checkout/releases/latest ) for the latest release notes.
2019-07-23 22:32:03 +03:00
2019-12-03 18:28:59 +03:00
# Usage
2019-09-05 18:42:49 +03:00
2019-12-03 18:28:59 +03:00
<!-- start usage -->
2019-07-23 22:32:03 +03:00
```yaml
2023-09-05 16:21:52 +03:00
- uses: actions/checkout@v4
2019-07-23 22:32:03 +03:00
with:
2019-12-04 00:47:19 +03:00
# Repository name with owner. For example, actions/checkout
2019-12-03 18:28:59 +03:00
# Default: ${{ github.repository }}
repository: ''
2019-12-12 21:49:26 +03:00
# The branch, tag or SHA to checkout. When checking out the repository that
2019-12-05 07:43:03 +03:00
# triggered a workflow, this defaults to the reference or SHA for that event.
2020-06-16 20:41:01 +03:00
# Otherwise, uses the default branch.
2019-12-03 18:28:59 +03:00
ref: ''
2020-03-11 22:55:17 +03:00
# 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.
#
2020-03-12 18:42:38 +03:00
# We recommend using a service account with the least permissions necessary. Also
# when generating a new PAT, select the least scopes necessary.
2020-03-11 22:55:17 +03:00
#
# [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 )
#
2019-12-03 18:28:59 +03:00
# Default: ${{ github.token }}
token: ''
2020-03-12 18:42:38 +03:00
# 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
2020-03-11 22:55:17 +03:00
# post-job step removes the SSH key.
#
2020-03-12 18:42:38 +03:00
# We recommend using a service account with the least permissions necessary.
2020-03-11 22:55:17 +03:00
#
# [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: ''
2024-04-18 22:29:55 +03:00
# The user to use when connecting to the remote SSH host. By default 'git' is
# used.
# Default: git
ssh-user: ''
2020-03-11 22:55:17 +03:00
# Whether to configure the token or SSH key with the local git config
2019-12-12 21:49:26 +03:00
# Default: true
persist-credentials: ''
2019-12-03 18:28:59 +03:00
# 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: ''
2023-09-22 20:30:36 +03:00
# Partially clone against a given filter. Overrides sparse-checkout if set.
# Default: null
filter: ''
2023-06-09 16:08:21 +03:00
# Do a sparse checkout on given patterns. Each pattern should be separated with
2023-09-22 20:30:36 +03:00
# new lines.
2023-06-09 16:08:21 +03:00
# Default: null
sparse-checkout: ''
# Specifies whether to use cone-mode when doing a sparse checkout.
# Default: true
sparse-checkout-cone-mode: ''
2020-07-13 04:02:24 +03:00
# Number of commits to fetch. 0 indicates all history for all branches and tags.
2019-12-03 18:28:59 +03:00
# Default: 1
fetch-depth: ''
2023-08-16 23:34:54 +03:00
# Whether to fetch tags, even if fetch-depth > 0.
# Default: false
fetch-tags: ''
2023-09-01 21:19:18 +03:00
# Whether to show progress status output when fetching.
# Default: true
show-progress: ''
2019-12-03 18:28:59 +03:00
# Whether to download Git-LFS files
# Default: false
lfs: ''
2020-03-05 22:21:59 +03:00
# Whether to checkout submodules: `true` to checkout submodules or `recursive` to
# recursively checkout submodules.
2020-03-11 22:55:17 +03:00
#
# When the `ssh-key` input is not provided, SSH URLs beginning with
# `git@github.com:` are converted to HTTPS.
#
2020-03-05 22:21:59 +03:00
# Default: false
submodules: ''
2022-04-21 04:37:43 +03:00
# Add repository path as safe.directory for Git global config by running `git
# config --global --add safe.directory < path > `
# Default: true
set-safe-directory: ''
2022-09-26 19:34:52 +03:00
# 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: ''
2019-07-23 22:32:03 +03:00
```
2019-12-03 18:28:59 +03:00
<!-- end usage -->
2019-07-23 22:32:03 +03:00
2019-12-14 00:39:47 +03:00
# Scenarios
2023-06-09 16:08:21 +03:00
- [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 )
2020-05-27 16:54:28 +03:00
- [Fetch all history for all tags and branches ](#Fetch-all-history-for-all-tags-and-branches )
2019-12-14 00:39:47 +03:00
- [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 )
2020-07-14 20:08:52 +03:00
- [Push a commit using the built-in token ](#Push-a-commit-using-the-built-in-token )
2020-05-27 16:54:28 +03:00
2023-06-09 16:08:21 +03:00
## Fetch only the root files
```yaml
2023-09-05 16:21:52 +03:00
- uses: actions/checkout@v4
2023-06-09 16:08:21 +03:00
with:
sparse-checkout: .
```
## Fetch only the root files and `.github` and `src` folder
```yaml
2023-09-05 16:21:52 +03:00
- uses: actions/checkout@v4
2023-06-09 16:08:21 +03:00
with:
sparse-checkout: |
.github
src
```
## Fetch only a single file
```yaml
2023-09-05 16:21:52 +03:00
- uses: actions/checkout@v4
2023-06-09 16:08:21 +03:00
with:
sparse-checkout: |
README.md
sparse-checkout-cone-mode: false
```
2020-05-27 16:54:28 +03:00
## Fetch all history for all tags and branches
```yaml
2023-09-05 16:21:52 +03:00
- uses: actions/checkout@v4
2020-05-27 16:54:28 +03:00
with:
fetch-depth: 0
```
2019-12-14 00:39:47 +03:00
2019-12-03 18:28:59 +03:00
## Checkout a different branch
2019-09-05 18:42:49 +03:00
```yaml
2023-09-05 16:21:52 +03:00
- uses: actions/checkout@v4
2019-09-05 18:42:49 +03:00
with:
2019-12-14 00:39:47 +03:00
ref: my-branch
2019-09-05 18:42:49 +03:00
```
2019-12-14 00:39:47 +03:00
## Checkout HEAD^
2019-12-03 18:28:59 +03:00
2019-10-25 17:52:59 +03:00
```yaml
2023-09-05 16:21:52 +03:00
- uses: actions/checkout@v4
2019-10-25 17:52:59 +03:00
with:
2019-12-14 00:39:47 +03:00
fetch-depth: 2
- run: git checkout HEAD^
```
## Checkout multiple repos (side by side)
```yaml
- name: Checkout
2023-09-05 16:21:52 +03:00
uses: actions/checkout@v4
2019-12-14 00:39:47 +03:00
with:
path: main
- name: Checkout tools repo
2023-09-05 16:21:52 +03:00
uses: actions/checkout@v4
2019-12-14 00:39:47 +03:00
with:
repository: my-org/my-tools
path: my-tools
```
2022-12-17 00:06:54 +03:00
> - If your secondary repository is private you will need to add the option noted in [Checkout multiple repos (private)](#Checkout-multiple-repos-private)
2019-12-14 00:39:47 +03:00
## Checkout multiple repos (nested)
```yaml
- name: Checkout
2023-09-05 16:21:52 +03:00
uses: actions/checkout@v4
2019-12-14 00:39:47 +03:00
- name: Checkout tools repo
2023-09-05 16:21:52 +03:00
uses: actions/checkout@v4
2019-12-14 00:39:47 +03:00
with:
repository: my-org/my-tools
path: my-tools
```
2022-12-17 00:06:54 +03:00
> - If your secondary repository is private you will need to add the option noted in [Checkout multiple repos (private)](#Checkout-multiple-repos-private)
2019-12-14 00:39:47 +03:00
## Checkout multiple repos (private)
```yaml
- name: Checkout
2023-09-05 16:21:52 +03:00
uses: actions/checkout@v4
2019-12-14 00:39:47 +03:00
with:
path: main
- name: Checkout private tools
2023-09-05 16:21:52 +03:00
uses: actions/checkout@v4
2019-12-14 00:39:47 +03:00
with:
repository: my-org/my-private-tools
2021-11-03 00:20:59 +03:00
token: ${{ secrets.GH_PAT }} # `GH_PAT` is a secret that contains your PAT
2019-12-14 00:39:47 +03:00
path: my-tools
2019-10-25 17:52:59 +03:00
```
2019-12-14 00:39:47 +03:00
> - `${{ 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
2019-12-04 18:12:10 +03:00
```yaml
2023-09-05 16:21:52 +03:00
- uses: actions/checkout@v4
2019-12-04 18:12:10 +03:00
with:
2019-12-10 19:17:38 +03:00
ref: ${{ github.event.pull_request.head.sha }}
2019-12-04 18:12:10 +03:00
```
2019-12-14 00:39:47 +03:00
## Checkout pull request on closed event
```yaml
on:
pull_request:
2020-07-14 16:23:30 +03:00
branches: [main]
2019-12-14 00:39:47 +03:00
types: [opened, synchronize, closed]
jobs:
build:
runs-on: ubuntu-latest
steps:
2023-09-05 16:21:52 +03:00
- uses: actions/checkout@v4
2019-12-14 00:39:47 +03:00
```
2020-07-14 20:08:52 +03:00
## Push a commit using the built-in token
```yaml
on: push
jobs:
build:
runs-on: ubuntu-latest
steps:
2023-09-05 16:21:52 +03:00
- uses: actions/checkout@v4
2020-07-14 20:08:52 +03:00
- run: |
date > generated.txt
2024-04-30 18:50:54 +03:00
# 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"
2020-07-14 20:08:52 +03:00
git add .
git commit -m "generated"
git push
```
2024-09-02 16:53:38 +03:00
*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
2020-07-14 20:08:52 +03:00
2019-07-23 22:32:03 +03:00
# License
The scripts and documentation in this project are released under the [MIT License ](LICENSE )