# How to Use the actions/checkout Action in GitHub Actions Workflows

> Learn to use the actions/checkout action in GitHub Actions. Clone your repository efficiently with support for sparse checkouts, LFS, submodules, and cross-repo authentication.

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

---

**The actions/checkout action clones your repository into `$GITHUB_WORKSPACE` using configurable inputs defined in [`action.yml`](https://github.com/actions/checkout/blob/main/action.yml) and orchestrated through [`src/main.ts`](https://github.com/actions/checkout/blob/main/src/main.ts), supporting sparse checkouts, LFS, submodules, and cross-repository authentication.**

The `actions/checkout` repository is the official JavaScript-based composite action that handles repository checkouts in GitHub Actions workflows. According to the actions/checkout source code, it normalizes inputs, validates security constraints, and executes Git commands to make your code available to subsequent workflow steps. Understanding its implementation helps you optimize fetch performance and secure your CI/CD pipelines.

## How the actions/checkout Action Works

### Architecture Overview

The action consists of several TypeScript modules that handle specific responsibilities:

| Component | Role | Source File |
|-----------|------|-------------|
| **action.yml** | Declares inputs, defaults, and the entry point script that the runner executes. | [`action.yml`](https://github.com/actions/checkout/blob/main/action.yml) |
| **src/main.ts** | Entry point that orchestrates the checkout process by invoking input parsing and Git operations. | [`src/main.ts`](https://github.com/actions/checkout/blob/main/src/main.ts) |
| **src/input-helper.ts** | Parses and validates all `with:` inputs, normalizes repository names, and constructs the `IGitSourceSettings` object. | [`src/input-helper.ts`](https://github.com/actions/checkout/blob/main/src/input-helper.ts) |
| **src/git-source-provider.ts** | Executes concrete Git commands including `git init`, `git fetch`, `git checkout`, and handles sparse-checkout configurations. | [`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts) |
| **src/unsafe-pr-checkout-helper.ts** | Implements security guards that block checkouts from forked pull requests unless explicitly allowed. | [`src/unsafe-pr-checkout-helper.ts`](https://github.com/actions/checkout/blob/main/src/unsafe-pr-checkout-helper.ts) |

### Execution Flow

The checkout process follows a strict sequence implemented in the source code:

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 validates the repository reference.

2. **Safety Validation** – The system checks the `allow-unsafe-pr-checkout` flag against the pull request origin to prevent "pull-request-target" attacks from forked repositories.

3. **Git Environment Setup** – [`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts) creates a fresh work-tree under `$GITHUB_WORKSPACE/<path>` and configures authentication tokens or SSH keys in the local Git config.

4. **Fetching Code** – Based on `fetch-depth`, `filter`, `fetch-tags`, `lfs`, and `submodules` settings, the action executes optimized `git fetch` commands to minimize bandwidth and time.

5. **Checkout and Sparse Configuration** – The requested `ref` (branch, tag, SHA, or PR head) is checked out. If `sparse-checkout` is enabled, the action configures `git sparse-checkout` before fetching to limit downloaded data.

6. **Credential Cleanup** – Unless `persist-credentials: false` is set, the temporary token is removed from the Git config during the action’s post-step to prevent credential leakage.

## Common Usage Patterns for actions/checkout

### Minimal Checkout

Use this pattern to check out the current repository at the triggering commit:

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

```

### Checkout Specific Branches or Tags

Target a specific reference by using the `ref` input parameter:

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

```

Replace `my-branch` with any tag name (e.g., `v1.2.3`) or commit SHA.

### Fetch Full Git History

By default, the action performs a shallow clone (`fetch-depth: 1`). For commands requiring complete history like `git log` or `git describe`, fetch all commits:

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

```

### Sparse Checkout for Large Repositories

Download only specific files or directories to reduce fetch time and disk usage:

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

```

Set `sparse-checkout-cone-mode: false` when listing individual files rather than directory patterns.

### Enable Git LFS

For repositories using Large File Storage, add the `lfs` flag:

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

```

### Checkout Submodules

Fetch nested dependencies recursively:

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

```

### Access Private Repositories

Checkout a different repository using a Personal Access Token (PAT) with appropriate scopes:

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

```

### Checkout Pull Request Head Commit

Access the actual PR head SHA instead of the merge commit:

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

```

## Security Considerations for actions/checkout

The action includes protections against unsafe pull request checkouts. By default, [`src/unsafe-pr-checkout-helper.ts`](https://github.com/actions/checkout/blob/main/src/unsafe-pr-checkout-helper.ts) prevents checking out code from forked repositories when the workflow is triggered by `pull_request_target` events.

Only enable unsafe checkouts after reviewing the security implications:

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

```

This bypasses the safety check implemented in [`src/unsafe-pr-checkout-helper.ts`](https://github.com/actions/checkout/blob/main/src/unsafe-pr-checkout-helper.ts) and should only be used when you explicitly trust the forked code.

## Summary

- **actions/checkout** is a JavaScript composite action that clones repositories into `$GITHUB_WORKSPACE` using configurations defined in [`action.yml`](https://github.com/actions/checkout/blob/main/action.yml).
- The execution flow involves [`src/input-helper.ts`](https://github.com/actions/checkout/blob/main/src/input-helper.ts) for parsing, [`src/unsafe-pr-checkout-helper.ts`](https://github.com/actions/checkout/blob/main/src/unsafe-pr-checkout-helper.ts) for security validation, and [`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts) for Git operations.
- Use `fetch-depth: 0` for full history, `sparse-checkout` for partial clones, and `lfs: true` for Large File Storage support.
- Always protect against unsafe PR checkouts unless explicitly requiring forked code access.

## Frequently Asked Questions

### What is the default fetch depth for actions/checkout?

By default, **actions/checkout** uses `fetch-depth: 1`, which performs a shallow clone containing only the latest commit. This minimizes checkout time and disk usage. Change this to `0` in your workflow configuration to fetch the complete history when running commands like `git describe` or `git log`.

### How do I checkout a different repository using actions/checkout?

Specify the `repository` input using the `owner/repo` format and provide authentication via the `token` input. For private repositories, use a Personal Access Token (PAT) stored in GitHub Secrets. The [`src/input-helper.ts`](https://github.com/actions/checkout/blob/main/src/input-helper.ts) module resolves the repository name and configures the authentication token in the Git config before fetching.

### Why is my sparse checkout not working correctly?

Ensure you set `sparse-checkout-cone-mode: false` when listing individual files rather than directory patterns. According to the implementation in [`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts), the action configures `git sparse-checkout` before fetching, so incorrect cone mode settings will cause the sparse patterns to fail silently or fetch unintended files.

### Is it safe to use allow-unsafe-pr-checkout in production?

Only use `allow-unsafe-pr-checkout: true` after thoroughly reviewing the security implications. The [`src/unsafe-pr-checkout-helper.ts`](https://github.com/actions/checkout/blob/main/src/unsafe-pr-checkout-helper.ts) file contains logic that blocks checkouts from forked pull requests to prevent attackers from exfiltrating secrets or modifying your codebase. Only enable this flag when you explicitly need to test code from forks and have implemented additional security controls.