How to Perform a Shallow Clone with actions/checkout

Yes, actions/checkout performs a shallow clone by default using fetch-depth: 1, which fetches only the latest commit to minimize network traffic and accelerate workflow execution.

The actions/checkout repository provides the official GitHub Action for checking out repositories in CI/CD workflows. By default, it implements a shallow clone strategy controlled by the fetch-depth input parameter, making it unnecessary to manually configure Git commands for most use cases.

Understanding the fetch-depth Default Behavior

The fetch-depth input determines how many commits to retrieve from the repository history. When omitted, the action defaults to 1, creating a shallow clone containing only the most recent commit of the triggered branch.

According to the source code in src/input-helper.ts, the input parsing occurs at lines 106-110:

// src/input-helper.ts
result.fetchDepth = Math.floor(Number(core.getInput('fetch-depth') || '1'))
if (isNaN(result.fetchDepth) || result.fetchDepth < 0) {
  result.fetchDepth = 0
}
core.debug(`fetch depth = ${result.fetchDepth}`)

When fetchDepth is greater than 0, the src/git-command-manager.ts constructs the git fetch command with the --depth flag, effectively running git fetch --depth=1 to retrieve only the tip of the branch.

Configuration Examples for Shallow Cloning

Default Shallow Clone (No Configuration Required)

Because fetch-depth defaults to 1, the simplest workflow automatically performs a shallow clone:

steps:
  - uses: actions/checkout@v7

This configuration retrieves only the single commit that triggered the workflow, reducing data transfer for large repositories.

Explicit Shallow Clone with Depth of 1

To explicitly declare the shallow clone behavior in your workflow:

steps:
  - uses: actions/checkout@v7
    with:
      fetch-depth: 1

Fetch Limited History (Last 5 Commits)

For workflows requiring recent history (e.g., for change detection or commit message analysis):

steps:
  - uses: actions/checkout@v7
    with:
      fetch-depth: 5

This retrieves the HEAD commit plus four additional ancestors while maintaining shallow clone benefits.

Full History Clone (Disable Shallow Clone)

To fetch complete history for all branches and tags, set fetch-depth to 0:

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

This executes a standard fetch without depth restrictions, pulling the entire commit graph.

Shallow Clone with Tags

To fetch tags while maintaining a minimal clone depth:

steps:
  - uses: actions/checkout@v7
    with:
      fetch-depth: 1
      fetch-tags: true

This combines minimal history retrieval with tag references.

Technical Implementation Details

The shallow clone functionality spans two key files in the actions/checkout repository:

• src/input-helper.ts: Parses the fetch-depth input string, converts it to a number using Math.floor(), and validates that it is non-negative. Invalid inputs automatically fall back to 0 (full history).

• src/git-command-manager.ts: Consumes the fetchDepth value from the IGitSourceSettings object and conditionally appends --depth=${fetchDepth} to the git fetch command when the value is greater than 0.

This architecture ensures consistent shallow cloning across Git providers while allowing granular control through the documented input parameters.

Summary

• actions/checkout defaults to fetch-depth: 1, creating a shallow clone automatically without additional configuration.
• Set fetch-depth: 0 to retrieve complete repository history and disable shallow cloning.
• Any positive integer creates a shallow clone limited to that specific number of commits.
• The implementation resides in src/input-helper.ts (input parsing) and src/git-command-manager.ts (command construction).
• Shallow clones significantly reduce network traffic and job startup time in CI/CD workflows.

Frequently Asked Questions

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

The default fetch-depth is 1, meaning the action performs a shallow clone by fetching only the latest commit. This behavior is defined in src/input-helper.ts where the input defaults to the string '1' when the workflow does not specify an explicit value.

How do I fetch all history instead of a shallow clone?

Set fetch-depth: 0 in your workflow configuration. This specific value triggers a full fetch without depth restrictions, retrieving the complete commit history for all branches and tags. The source code explicitly treats 0 as a special case that disables the --depth flag in the Git fetch command.

Can I fetch tags with a shallow clone?

Yes, combine fetch-depth: 1 with fetch-tags: true in your workflow inputs. This configuration maintains the performance benefits of a shallow clone while ensuring that Git tags are available in the workspace. Note that the tags will point to the limited set of commits based on your depth setting.

Why is shallow clone faster than full clone in GitHub Actions?

Shallow clones transfer significantly less data by excluding historical commits through the --depth flag, reducing network latency and storage requirements. For repositories with extensive commit history, fetching only the latest commit can reduce clone times from minutes to seconds, as implemented by the default shallow fetch strategy in src/git-command-manager.ts.

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