Git Version Required for SHA-256 Object Store Support in actions/checkout

actions/checkout requires Git 2.30 or newer to correctly initialize and operate on repositories using the SHA-256 object format, falling back to the REST API on older versions that cannot handle SHA-256 objects.

The actions/checkout GitHub Action supports repositories utilizing the modern SHA-256 object store format, but this capability depends entirely on the Git client version installed on your runner. When working with SHA-256 repositories, the action performs runtime version detection to determine whether it can use native Git commands or must fall back to alternative methods. Understanding the specific Git version required for SHA-256 object store support ensures your CI/CD workflows can successfully checkout these modern repositories.

How actions/checkout Detects SHA-256 Repositories

The action identifies SHA-256 repositories through detection logic implemented in src/git-source-provider.ts. When processing a repository, the code specifically checks for the SHA-256 object format and logs the message "Detected SHA-256 repository object format" at line 125 to indicate this state.

This detection triggers specific handling requirements that mandate Git 2.30 or newer for proper operations. Without this version, the action cannot rely on native Git commands to manage the SHA-256 object database.

Minimum Git Version Requirements

The action maintains two distinct version thresholds: a baseline requirement for general operation and a specific requirement for SHA-256 compatibility.

Overall Minimum (Git 2.18)

According to src/git-command-manager.ts at line 15, the action defines Git 2.18 as the absolute minimum version required for basic functionality. This version check applies to all checkout operations regardless of the object format used.

SHA-256 Specific Requirement (Git 2.30)

For repositories utilizing the SHA-256 object store, Git 2.30 is the minimum required version. This specific version marks when Git's SHA-256 object-store support became stable and production-ready. If the runner detects a Git version older than 2.30 when processing a SHA-256 repository, the action automatically falls back to the GitHub REST API download method, which provides limited functionality and does not support SHA-256 objects.

Verifying Your Runner's Git Version

Before running workflows against SHA-256 repositories, verify your runner meets the version requirements.

Check the installed Git version manually:

git --version

# Must report 2.30.* or newer for SHA-256 support

In a workflow context, explicitly verify the version before the checkout step:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Verify Git version compatibility
        run: |
          GIT_VERSION=$(git --version | awk '{print $3}')
          echo "Detected Git version: $GIT_VERSION"
          # Ensure version is >= 2.30 for SHA-256 repositories

      - uses: actions/checkout@v4
        with:
          repository: owner/sha256-repo
          ref: ${{ github.sha }}

What Happens with Older Git Versions?

When actions/checkout detects a SHA-256 repository but finds Git version 2.29 or older, it cannot use native Git commands to handle the object database. Instead, the action falls back to downloading repository contents via the GitHub REST API.

This fallback method has critical limitations for SHA-256 repositories. The REST API download approach does not support SHA-256 object formats, meaning the checkout will fail or provide incomplete results when attempting to work with these modern repositories. Consequently, ensuring Git 2.30+ availability on your runners is essential for SHA-256 compatibility.

Implementation Details

The version validation logic resides in specific source files within the actions/checkout repository:

• src/git-source-provider.ts (line 125): Contains the SHA-256 detection logic that identifies when a repository uses the SHA-256 object format.
• src/git-command-manager.ts (line 15): Defines the general minimum Git version constant (2.18) and implements the version validation utilities used throughout the action.
• CHANGELOG.md: Documents the history of SHA-256 support additions and version requirement updates.

The runtime version check compares the installed Git version against these thresholds before attempting operations that require specific object format support.

Summary

• Git 2.30 or newer is required to work with SHA-256 repositories using actions/checkout.
• The action detects SHA-256 format in src/git-source-provider.ts and logs the detection.
• Git versions below 2.18 are unsupported for any operations.
• Runners with Git 2.18–2.29 fall back to the REST API, which cannot handle SHA-256 objects.
• Verify versions using git --version before running checkout steps on SHA-256 repositories.

Frequently Asked Questions

What is the minimum Git version for actions/checkout?

The absolute minimum Git version is 2.18, defined in src/git-command-manager.ts. However, this only covers basic operations. For SHA-256 object store support specifically, you need Git 2.30 or newer.

Why does SHA-256 require Git 2.30 specifically?

Git 2.30 marks the release where SHA-256 object-store support became stable and production-ready. Earlier versions of Git either lacked SHA-256 support entirely or implemented it as experimental features that were not suitable for production use in CI/CD environments.

Can I use SHA-256 repositories on older runners?

No. Runners with Git versions older than 2.30 will fall back to the GitHub REST API when detecting SHA-256 repositories. Since the REST API does not support SHA-256 object formats, the checkout will not function correctly with these repositories. You must update the runner's Git installation or use a newer runner image.

How do I check if my repository uses SHA-256?

You can check your repository's object format locally by running git rev-parse --show-object-format in your repository root. If it returns sha256, your repository uses the SHA-256 object store and requires Git 2.30+ on any runners using actions/checkout.

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