How `fetch-depth` Configuration Affects `actions/checkout` Performance

Setting the fetch-depth input in actions/checkout controls whether Git performs a shallow clone (fast, minimal data) or full history fetch (slow, complete data), directly impacting CI workflow execution time and bandwidth usage.

The actions/checkout GitHub Action is the standard method for pulling repository code into CI workflows. By adjusting the fetch-depth configuration parameter, you control how much Git history is downloaded, creating a direct trade-off between checkout speed and the availability of historical commit data.

How fetch-depth Is Parsed

The action reads the fetch-depth input value in src/input-helper.ts (lines 122-128), where it is retrieved from the workflow configuration and normalized for the Git command manager.

This parsed value determines the behavior of subsequent fetch operations, serving as the primary mechanism for performance optimization in the checkout process.

Git Command Generation and Performance

The core performance logic resides in src/git-command-manager.ts (lines 299-306), where the action constructs the git fetch command based on the depth value.

Shallow Cloning (fetch-depth > 0)

When fetchDepth is greater than zero, the action appends --depth=<value> to the fetch command. This creates a shallow clone limited to the specified number of commits, dramatically reducing the amount of data transferred and speeding up the checkout process, especially for large repositories with extensive histories.

According to the source code in src/git-command-manager.ts (lines 299-301), this flag instructs Git to fetch only the recent commit history, minimizing network overhead.

Full History Unshallowing (fetch-depth = 0)

When fetchDepth is set to 0, the code checks whether a shallow repository already exists by looking for .git/shallow. If detected, it adds the --unshallow flag to retrieve the full history (lines 302-306 in src/git-command-manager.ts). This converts an existing shallow clone into a complete repository but requires significantly more time and bandwidth.

Performance Comparison by Configuration

fetch-depth value	Git command effect	Data transfer	Checkout speed	Best used for
1 (default)	--depth=1	Minimal	Fastest	Standard CI builds, minimal history
> 0	--depth=<n>	Reduced	Fast	Recent history analysis, limited depth needs
0	--unshallow (if shallow)	Complete	Slowest	Full changelog generation, version calculation

Practical Configuration Examples

Use these configurations to optimize your workflow performance based on your requirements:

# Fast shallow checkout – only the latest commit

- uses: actions/checkout@v4
  with:
    fetch-depth: 1   # default, minimal data transfer

# Full history – useful for tools that need the complete commit graph

- uses: actions/checkout@v4
  with:
    fetch-depth: 0   # disables shallow cloning, fetches all commits

# Deeper shallow clone – fetch the last 50 commits

- uses: actions/checkout@v4
  with:
    fetch-depth: 50

Testing and Verification

The behavior is validated by the test suite in __test__/git-command-manager.test.ts (lines 36-86), which confirms that the exact arguments are passed to git fetch for different fetch-depth values. These tests verify that the performance characteristics match the configuration, ensuring shallow clones use --depth and full history requests trigger --unshallow when appropriate.

Summary

• The fetch-depth parameter in actions/checkout directly translates to Git's --depth or --unshallow flags.
• Values greater than 0 trigger shallow clones, minimizing data transfer and maximizing checkout speed for CI pipelines.
• Setting fetch-depth to 0 forces a full history fetch, which is slower but necessary for workflows requiring complete commit graphs.
• The default value of 1 provides optimal performance for most CI workflows by fetching only the latest commit.

Frequently Asked Questions

What is the default fetch-depth in actions/checkout?

The default value is 1, which performs a shallow clone of only the most recent commit. This minimizes network usage and checkout time, making it ideal for standard CI builds that do not require historical data.

When should I use fetch-depth: 0?

Use fetch-depth: 0 when your workflow requires access to the complete Git history, such as for generating changelogs, calculating version bumps based on commit history, or running analysis tools that examine the full commit graph. Be aware this increases checkout time and bandwidth usage.

Does fetch-depth: 0 always download the full repository?

If the repository is already shallow, fetch-depth: 0 triggers the --unshallow flag to fetch the remaining history. If the repository already contains full history, the action fetches without depth restrictions, ensuring all commits are available without redundant data transfer.

How does fetch-depth affect large repository performance?

For large repositories with extensive histories, shallow cloning (fetch-depth > 0) can reduce checkout time from minutes to seconds by transferring only recent commits rather than the entire codebase history. This is a critical optimization for monorepos or long-running projects with thousands of commits.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}