# How to Use actions/checkout in GitHub Actions: Complete Implementation Guide

> Master actions/checkout in GitHub Actions. Learn how this essential action clones your repository and prepares your code for seamless workflow execution. Get the complete implementation guide now.

- Repository: [GitHub Actions/checkout](https://github.com/actions/checkout)
- Tags: how-to-guide
- Published: 2026-07-17

---

**The `actions/checkout` action clones your repository into `$GITHUB_WORKSPACE` by parsing workflow inputs through [`src/input-helper.ts`](https://github.com/actions/checkout/blob/main/src/input-helper.ts) and executing Git commands via [`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts), making your code available to subsequent steps.**

The `actions/checkout` action is the standard mechanism for accessing repository code inside GitHub Actions workflows. Understanding how to use `actions/checkout` in GitHub Actions effectively requires knowledge of its input parameters, internal execution flow, and security safeguards as implemented in the `actions/checkout` repository.

## How the Checkout Action Works

`actions/checkout` is a JavaScript-based action that orchestrates repository access through a specific execution pipeline. The runner reads [`action.yml`](https://github.com/actions/checkout/blob/main/action.yml) to determine available inputs and entry points, then executes the workflow defined in [`src/main.ts`](https://github.com/actions/checkout/blob/main/src/main.ts).

The execution flow follows these stages:

1. **Input Parsing** – The `getInputs()` function in [`src/input-helper.ts`](https://github.com/actions/checkout/blob/main/src/input-helper.ts) reads workflow parameters, applies defaults (such as `clean: true` and `fetch-depth: 1`), and constructs an `IGitSourceSettings` object.
2. **Safety Validation** – [`src/unsafe-pr-checkout-helper.ts`](https://github.com/actions/checkout/blob/main/src/unsafe-pr-checkout-helper.ts) validates the `allow-unsafe-pr-checkout` flag against pull request origins to prevent fork-based attacks.
3. **Git Configuration** – [`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts) initializes the repository, configures authentication tokens, and prepares the working directory under `$GITHUB_WORKSPACE/<path>`.
4. **Fetch and Checkout** – Based on settings like `fetch-depth`, `filter`, and `fetch-tags`, the provider executes `git fetch` and checks out the requested `ref`.
5. **Credential Cleanup** – Unless `persist-credentials: false` is set, the action removes temporary tokens from Git config during the post-step cleanup.

## Basic Usage Examples

### Minimal Checkout

The simplest usage checks out the current repository at the default branch:

```yaml
- uses: actions/checkout@v4

```

### Checkout Specific Branches or Tags

Use the `ref` input to checkout a specific branch, tag, or commit SHA:

```yaml
- uses: actions/checkout@v4
  with:
    ref: my-branch

```

### Fetch Full History

By default, the action performs a shallow fetch (depth 1). Set `fetch-depth: 0` to retrieve complete history for commands like `git log` or `git describe`:

```yaml
- uses: actions/checkout@v4
  with:
    fetch-depth: 0

```

## Advanced Configuration

### Sparse Checkout

Limit downloaded data by configuring sparse checkout patterns in [`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts) before the fetch:

```yaml
- uses: actions/checkout@v4
  with:
    sparse-checkout: |
      README.md
      src/
    sparse-checkout-cone-mode: false

```

### Large File Storage (LFS)

Enable Git LFS to handle large files:

```yaml
- uses: actions/checkout@v4
  with:
    lfs: true

```

### Submodule Handling

Checkout nested submodules recursively:

```yaml
- uses: actions/checkout@v4
  with:
    submodules: recursive

```

### Cross-Repository Access

Access private repositories using a Personal Access Token (PAT) stored in secrets:

```yaml
- uses: actions/checkout@v4
  with:
    repository: my-org/private-repo
    token: ${{ secrets.PAT }}

```

## Security Considerations

The action includes security protections implemented in [`src/unsafe-pr-checkout-helper.ts`](https://github.com/actions/checkout/blob/main/src/unsafe-pr-checkout-helper.ts). By default, it refuses to checkout code from forked pull requests unless explicitly authorized.

To checkout the PR head SHA instead of the merge commit:

```yaml
- uses: actions/checkout@v4
  with:
    ref: ${{ github.event.pull_request.head.sha }}

```

To opt-in to potentially unsafe checkouts (only after reviewing security implications):

```yaml
- uses: actions/checkout@v4
  with:
    allow-unsafe-pr-checkout: true

```

## Summary

- **`actions/checkout`** clones repositories into `$GITHUB_WORKSPACE` using a TypeScript-based implementation split across specialized source files.
- **Input processing** occurs in [`src/input-helper.ts`](https://github.com/actions/checkout/blob/main/src/input-helper.ts), which validates parameters and applies defaults before passing settings to the Git provider.
- **Security protections** in [`src/unsafe-pr-checkout-helper.ts`](https://github.com/actions/checkout/blob/main/src/unsafe-pr-checkout-helper.ts) prevent accidental execution of untrusted fork code without explicit opt-in.
- **Advanced features** include sparse checkout, LFS support, submodule handling, and cross-repository access via PAT authentication.

## Frequently Asked Questions

### How do I checkout a pull request branch instead of the merge commit?

Set the `ref` input to `${{ github.event.pull_request.head.sha }}` to checkout the actual PR head rather than the merge commit. This configuration is useful when you need the exact commit state without GitHub's automatic merge into the base branch.

### Why does my workflow fail when accessing private repositories?

Private repository access requires authentication via the `token` input. Configure a Personal Access Token with `repo` scope stored in repository secrets, then pass it to the action using `token: ${{ secrets.PAT }}`. The default `GITHUB_TOKEN` only has access to the current repository.

### When should I use fetch-depth: 0 versus the default shallow checkout?

Use `fetch-depth: 0` when your workflow requires complete Git history, such as for semantic versioning tools, `git describe`, or changelog generation. The default shallow checkout (depth 1) improves performance and reduces disk usage for builds that only need the latest commit.

### What files control the actions/checkout behavior?

The action behavior is defined in [`action.yml`](https://github.com/actions/checkout/blob/main/action.yml) (interface definition), [`src/main.ts`](https://github.com/actions/checkout/blob/main/src/main.ts) (entry point), [`src/input-helper.ts`](https://github.com/actions/checkout/blob/main/src/input-helper.ts) (input validation), and [`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts) (Git command execution). Understanding these files helps debug complex checkout scenarios or contribute to the action.