# What Happens When Git 2.18 or Higher Is Not in the Runner's PATH: REST API Fallback Explained

> Discover what happens when Git 2.18+ is missing from your runner PATH. actions/checkout falls back to the GitHub REST API, disabling Git features. Learn more.

- Repository: [GitHub Actions/checkout](https://github.com/actions/checkout)
- Tags: internals
- Published: 2026-07-18

---

**When Git 2.18 or higher is not available in the runner's PATH, `actions/checkout` automatically falls back to the GitHub REST API to download repository files, disabling Git-specific features like submodules and SSH authentication.**

The `actions/checkout` action requires a local Git client version 2.18 or newer to perform full Git-based operations. When the runner cannot locate a qualifying Git binary, the action switches to an alternative download mechanism that retrieves files without creating a local Git repository. This behavior ensures workflows can still access repository contents on minimal or specialized runners, though with reduced functionality.

## How the Git Version Detection Works

The action implements a strict version checking system across three core TypeScript modules to determine whether native Git commands can be used.

### Parsing Git Version Output

In [`src/git-version.ts`](https://github.com/actions/checkout/blob/main/src/git-version.ts), the action parses the output of `git --version` to create a structured `GitVersion` instance. This class handles semantic version comparison logic, allowing the action to determine precisely which Git features are available on the runner.

### Enforcing the Minimum Version Requirement

The [`src/git-command-manager.ts`](https://github.com/actions/checkout/blob/main/src/git-command-manager.ts) file defines the minimum requirement as a constant:

```typescript
MinimumGitVersion = new GitVersion('2.18')

```

The `GitCommandManager` class compares the detected version against this threshold using the `checkMinimum()` method. If the runner's Git installation is older than 2.18 or entirely absent, this check returns false, triggering the fallback mechanism.

## The REST API Fallback Mechanism

When the version check fails, [`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts) executes alternative logic to retrieve repository contents without invoking Git commands.

### Fallback Decision Logic

The provider contains explicit conditional logic similar to:

```typescript
if (!this.gitVersion.checkMinimum(MinimumGitVersion)) {
  // Use the GitHub REST API to download the files
}

```

When this condition evaluates to true, the action abandons the Git-based checkout path and instead makes HTTP requests to the GitHub REST API to fetch the repository archive. This results in a file download behavior equivalent to downloading a ZIP archive of the repository rather than performing a `git clone`.

### Download Behavior and Limitations

The REST API fallback retrieves the repository as a flat set of files, similar to a shallow checkout. **No `.git` directory is created**, meaning subsequent workflow steps cannot execute Git commands like `git log`, `git fetch`, or `git push` against the downloaded contents.

## Disabled Features and Error Handling

Because the REST API cannot handle Git-specific operations, several `actions/checkout` inputs become unavailable when falling back to API-based downloads.

### Blocked Configuration Options

The action disables support for:

- **submodules**: Recursive repository dependencies cannot be fetched
- **ssh-key**: SSH authentication requires Git transport protocols
- **ssh-known-hosts**: SSH host key verification depends on native Git SSH capabilities

### Error Messages for Invalid Inputs

If your workflow attempts to use these features without Git 2.18 available, the action emits a clear error message:

> Input 'submodules' not supported when falling back to download using the GitHub REST API. To create a local Git repository instead, add Git 2.18 or higher to the PATH.

This prevents silent failures and immediately alerts you to the configuration conflict.

## Practical Workflow Examples

Understanding the fallback behavior helps you design resilient workflows that either accommodate the REST API limitations or ensure Git availability.

### Standard Checkout Without Git 2.18

On a runner lacking Git 2.18 or higher, this workflow succeeds but disables Git features:

```yaml
steps:
  - name: Checkout without local Git
    uses: actions/checkout@v7
    with:
      submodules: true  # ❌ Causes error: submodules not supported in REST API fallback

```

The action completes the file download but fails when processing the `submodules` input, outputting the error message shown above.

### Installing Git to Enable Native Checkout

To avoid the REST API fallback and restore full Git functionality, install Git 2.18+ before the checkout step:

```yaml
steps:
  - name: Install Git 2.30
    run: |
      sudo apt-get update
      sudo apt-get install -y git
  - uses: actions/checkout@v7  # Uses native Git commands

```

With Git 2.18 or higher present in the PATH, [`src/git-command-manager.ts`](https://github.com/actions/checkout/blob/main/src/git-command-manager.ts) validates the version successfully, and [`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts) executes a standard Git clone with full history and submodule support.

## Summary

- **`actions/checkout` requires Git ≥2.18** for full Git-based operations, enforced in [`src/git-command-manager.ts`](https://github.com/actions/checkout/blob/main/src/git-command-manager.ts) via the `MinimumGitVersion` constant.
- **Automatic REST API fallback** occurs when Git is missing or outdated, implemented in [`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts) through version checking logic.
- **Feature restrictions apply** during fallback: submodules, SSH keys, and SSH known hosts are unavailable because the REST API provides only file downloads.
- **No Git history is preserved** in fallback mode, preventing subsequent Git commands from functioning in the workflow.
- **Resolution requires installing Git 2.18+** in the runner environment to restore native Git functionality and access all action inputs.

## Frequently Asked Questions

### What error message appears if I use submodules without Git 2.18 installed?

You receive the error: "Input 'submodules' not supported when falling back to download using the GitHub REST API. To create a local Git repository instead, add Git 2.18 or higher to the PATH." This indicates the action detected insufficient Git capabilities and cannot process the submodule request.

### Can I still run Git commands after the REST API fallback completes?

No. The REST API fallback downloads files as a flat archive without initializing a Git repository. No `.git` directory exists in the workspace, so commands like `git status`, `git log`, or `git push` will fail with "not a git repository" errors.

### How does actions/checkout detect the Git version?

The action executes `git --version` and parses the output in [`src/git-version.ts`](https://github.com/actions/checkout/blob/main/src/git-version.ts) to create a `GitVersion` object. This object compares against `MinimumGitVersion = new GitVersion('2.18')` defined in [`src/git-command-manager.ts`](https://github.com/actions/checkout/blob/main/src/git-command-manager.ts) using the `checkMinimum()` method.

### Does the REST API fallback download the full git history?

No. The fallback retrieves only the current files in the repository, similar to a shallow checkout or ZIP download. You get the working tree contents without commit history, branches, or tags, as the GitHub REST API content endpoints provide only snapshot archives.