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

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, 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 file defines the minimum requirement as a constant:

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 executes alternative logic to retrieve repository contents without invoking Git commands.

Fallback Decision Logic

The provider contains explicit conditional logic similar to:

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:

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:

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 validates the version successfully, and 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 via the MinimumGitVersion constant.
• Automatic REST API fallback occurs when Git is missing or outdated, implemented in 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 to create a GitVersion object. This object compares against MinimumGitVersion = new GitVersion('2.18') defined in 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.

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