# How actions/checkout Supports SHA-256 Repository Object Format

> actions/checkout automatically supports SHA-256 repositories using the GitHub API and the --object-format=sha256 flag for seamless compatibility. Learn how.

- Repository: [GitHub Actions/checkout](https://github.com/actions/checkout)
- Tags: deep-dive
- Published: 2026-08-30

---

**actions/checkout** automatically detects SHA-256 repositories via the GitHub API and initializes local clones with the `--object-format=sha256` flag to ensure seamless compatibility with the modern object format.

The **actions/checkout** GitHub Action provides transparent support for repositories using the **SHA-256 object format**, Git's secure alternative to the legacy SHA-1 hashing algorithm. When checking out code from repositories that have migrated to SHA-256, the action dynamically configures the local Git environment without requiring manual configuration or workflow changes. This implementation ensures that CI/CD pipelines work reliably across both traditional and next-generation repository formats.

## Detecting the Object Format via GitHub API

The detection process begins in [`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts), which orchestrates the cloning operation for fresh checkouts. During initialization, the action calls `githubApiHelper.tryGetRepositoryObjectFormat` to determine the repository's hashing algorithm.

This helper method, defined in [`src/github-api-helper.ts`](https://github.com/actions/checkout/blob/main/src/github-api-helper.ts), sends an authenticated request to GitHub's repository-object-format endpoint. The function inspects the response header **`X-GitHub-Object-Format`** to identify the format:

- If the header value equals `sha256`, the helper returns `{succeeded: true, format: 'sha256'}`
- For standard repositories, it returns the SHA-1 default or indicates detection failure

This detection occurs transparently before any Git commands execute, ensuring the action knows whether to prepare a SHA-256 compatible environment.

## Initializing the Repository with SHA-256 Support

Once the object format is identified, [`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts) passes the format string to `git.init(objectFormat)`. The `init` method in [`src/git-command-manager.ts`](https://github.com/actions/checkout/blob/main/src/git-command-manager.ts) translates this parameter into the appropriate command-line flag.

When SHA-256 is detected, the action executes:

```bash
git init --object-format=sha256

```

For standard SHA-1 repositories, the action runs `git init` without the flag, using Git's default behavior. This conditional initialization ensures that the local repository can store, fetch, and manipulate SHA-256 objects without hash mismatches or corruption errors.

The [`git-command-manager.ts`](https://github.com/actions/checkout/blob/main/git-command-manager.ts) file handles the argument construction and execution, ensuring the `--object-format` flag is only passed when supported by the detected Git version and required by the remote repository.

## Handling SHA-256 References in Fetch Operations

After initialization, the action uses the same fetch logic regardless of object format, but specific components are updated to recognize SHA-256 commit identifiers. The **ref-helper** module contains regular expressions that validate commit SHAs, including support for 64-character hexadecimal strings used by SHA-256.

The test suite in **[`__test__/ref-helper.test.ts`](https://github.com/actions/checkout/blob/main/__test__/ref-helper.test.ts)** explicitly verifies that SHA-256 merge-commit SHAs are matched correctly. This ensures that when parsing merge commit information or validating reference names, the action correctly identifies 64-character SHA-256 hashes alongside traditional 40-character SHA-1 hashes.

## Git Version Requirements and Fallback Behavior

Supporting SHA-256 objects requires **Git 2.34 or higher**, the version that introduced the `--object-format=sha256` flag. The action checks the installed Git version when creating the command manager instance.

If the runner's Git version is insufficient:

- The action abandons the clone strategy
- It falls back to downloading the repository via the GitHub REST API as an archive
- This ensures workflows continue functioning even on older runner images, though without full Git history

This version check occurs in [`src/git-command-manager.ts`](https://github.com/actions/checkout/blob/main/src/git-command-manager.ts) during initialization, providing graceful degradation for environments that haven't upgraded to Git 2.34+.

## Configuration Examples

No special configuration is required to support SHA-256 repositories. Standard checkout steps work automatically:

```yaml

# Works for both SHA-1 and SHA-256 repositories transparently

steps:
  - uses: actions/checkout@v4

```

For performance optimization with SHA-256 repositories, you can still use shallow clones:

```yaml
steps:
  - uses: actions/checkout@v4
    with:
      fetch-depth: 1

```

For testing scenarios where you need to force SHA-256 initialization regardless of API detection, set the environment variable before the checkout step:

```yaml
steps:
  - uses: actions/checkout@v4
    env:
      GIT_OBJECT_FORMAT: sha256

```

Note that forcing the object format is **not required** for normal operation and should only be used in specific debugging or testing scenarios.

## Summary

- **actions/checkout** detects SHA-256 format via the `X-GitHub-Object-Format` header using `githubApiHelper.tryGetRepositoryObjectFormat` in [`src/github-api-helper.ts`](https://github.com/actions/checkout/blob/main/src/github-api-helper.ts).
- The action initializes repositories with `git init --object-format=sha256` through the `git.init()` method implemented in [`src/git-command-manager.ts`](https://github.com/actions/checkout/blob/main/src/git-command-manager.ts).
- SHA-256 commit references are validated using updated regex patterns in the ref-helper module, with explicit test coverage in [`__test__/ref-helper.test.ts`](https://github.com/actions/checkout/blob/main/__test__/ref-helper.test.ts).
- Git version 2.34 or higher is required for native SHA-256 support; older versions trigger a fallback to REST API archive downloads.

## Frequently Asked Questions

### Does actions/checkout require special configuration for SHA-256 repositories?

No. The action automatically detects the object format via the GitHub API and configures the local Git environment without requiring additional inputs or workflow modifications. Both SHA-1 and SHA-256 repositories work with the standard `uses: actions/checkout@v4` syntax.

### What Git version is required to support SHA-256 repositories?

Git version 2.34 or higher is required to initialize repositories with the `--object-format=sha256` flag. If the runner uses an older Git version, the action automatically falls back to downloading the repository as an archive via the GitHub REST API instead of performing a full clone.

### How does the action detect whether a repository uses SHA-256?

The action queries GitHub's repository-object-format endpoint through `tryGetRepositoryObjectFormat()` and checks the `X-GitHub-Object-Format` response header. When this header contains `sha256`, the action passes this information to the Git initialization routine to create a compatible local repository structure.

### Can I force SHA-256 initialization even if the API doesn't report it?

While you can set the `GIT_OBJECT_FORMAT` environment variable to `sha256` before the checkout step, this is not recommended for normal workflows. The action handles object format detection automatically, and manual overrides should only be used for specific testing scenarios or debugging purposes.