How to Configure Shallow Clone in actions/checkout

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, 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 and processed by the input validation layer in src/input-helper.ts.

Configuration Examples

Default Shallow Clone (Single Commit)

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

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.

Full Clone with Complete History

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

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:

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:

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: Defines the input schema for fetch-depth and fetch-tags, specifying default values and accepted types for the action interface.
• 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: 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 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.

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