# How to Configure Shallow Clone in actions/checkout

> Configure shallow clone in actions/checkout repository using fetch-depth. Control clone depth for faster workflows by setting it to 1 for a single commit or a specific integer.

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

---

**Use the `fetch-depth` input to control clone depth—set it to `1` for a single commit (default), `0` for full history, or any positive integer to fetch a specific number of recent commits.**

The `actions/checkout` GitHub Action optimizes CI performance by performing shallow clones by default, fetching only the commit that triggered the workflow. This behavior is controlled through the `fetch-depth` input parameter defined in [`action.yml`](https://github.com/actions/checkout/blob/main/action.yml), which determines how much Git history is retrieved during the checkout process.

## How Shallow Clone Configuration Works

The `fetch-depth` input accepts integer values that drastically change the cloning behavior:

- **`fetch-depth: 1`** (default): Fetches only the single commit that triggered the workflow, creating the shallowest possible clone.
- **`fetch-depth: 0`**: Performs a full clone, retrieving all branches, tags, and complete history.
- **`fetch-depth: >0`** (e.g., `5`, `10`): Performs a shallow clone limited to the specified number of recent commits.

When `fetch-depth` is greater than `0`, the action fetches tags only if you explicitly set `fetch-tags: true`. This logic is implemented in the action's input schema within [`action.yml`](https://github.com/actions/checkout/blob/main/action.yml) and processed by the input validation layer in [`src/input-helper.ts`](https://github.com/actions/checkout/blob/main/src/input-helper.ts).

## Configuration Examples

### Default Shallow Clone (Single Commit)

By default, `actions/checkout` performs a shallow clone with no additional configuration:

```yaml
steps:
  - name: Checkout repository
    uses: actions/checkout@v4

```

This configuration fetches only the commit that triggered the workflow run, minimizing network usage and checkout time according to the implementation in [`src/git-command-manager.ts`](https://github.com/actions/checkout/blob/main/src/git-command-manager.ts).

### Full Clone with Complete History

For workflows requiring full Git history, such as changelog generation or commit analysis:

```yaml
steps:
  - name: Checkout with full history
    uses: actions/checkout@v4
    with:
      fetch-depth: 0

```

Setting `fetch-depth: 0` disables shallow cloning and retrieves all commits, tags, and branches from the repository.

### Partial Shallow Clone with Specific Depth

To fetch a limited history while keeping the clone lightweight:

```yaml
steps:
  - name: Checkout last 10 commits
    uses: actions/checkout@v4
    with:
      fetch-depth: 10

```

This retrieves the 10 most recent commits, useful for tools like `git diff` or `git log` that need recent context without the overhead of full repository history.

### Shallow Clone with Tags

When you need tags available in a shallow clone:

```yaml
steps:
  - name: Checkout with tags
    uses: actions/checkout@v4
    with:
      fetch-depth: 10
      fetch-tags: true

```

The `fetch-tags: true` parameter ensures Git fetches tag references even when using a shallow clone depth, as the default behavior excludes tags when `fetch-depth` is specified.

## Source Code Implementation

The shallow clone functionality is implemented across several key files in the repository:

- **[`action.yml`](https://github.com/actions/checkout/blob/main/action.yml)**: Defines the input schema for `fetch-depth` and `fetch-tags`, specifying default values and accepted types for the action interface.
- **[`src/input-helper.ts`](https://github.com/actions/checkout/blob/main/src/input-helper.ts)**: Parses and validates the `fetch-depth` value at runtime, converting string inputs to integers and applying default behavior when the input is omitted.
- **[`src/git-command-manager.ts`](https://github.com/actions/checkout/blob/main/src/git-command-manager.ts)**: Executes the underlying `git fetch` commands, constructing the appropriate Git arguments based on the resolved depth value to perform either shallow or full fetches.

## Summary

- **`fetch-depth: 1`** is the default behavior, fetching only the latest commit for optimal CI performance.
- Set **`fetch-depth: 0`** when workflows require complete Git history, tags, and branch information.
- Use **`fetch-depth: N`** (where N > 0) to fetch a specific number of recent commits, balancing speed with history needs.
- Combine **`fetch-tags: true`** with shallow clones to ensure tags are available without fetching full history.

## Frequently Asked Questions

### What is the default clone depth in actions/checkout?

By default, `actions/checkout` uses `fetch-depth: 1`, which retrieves only the single commit that triggered the workflow run. This shallow clone is defined in [`action.yml`](https://github.com/actions/checkout/blob/main/action.yml) and minimizes checkout time and storage usage in CI environments.

### How do I fetch tags with a shallow clone?

Add `fetch-tags: true` to your workflow configuration alongside your `fetch-depth` value. By default, tags are not fetched when `fetch-depth` is greater than `0`, so this parameter is required to make annotated tags available in shallow clones.

### When should I use fetch-depth 0 instead of a shallow clone?

Use `fetch-depth: 0` when your workflow requires access to the complete Git history, such as generating changelogs, calculating version bumps based on commit messages, or running `git diff` between arbitrary commits. Shallow clones break these operations because they lack the necessary commit ancestry.

### Does fetch-depth affect performance significantly?

Yes, shallow clones with `fetch-depth: 1` are significantly faster and use less bandwidth than full clones, especially for large repositories with extensive history. However, if subsequent steps require full history, the overhead of unshallowing or fetching missing objects may negate the initial performance gains.