# Does actions/checkout Support Submodules with the REST API Fallback?

> Discover if actions/checkout supports submodules when falling back to the REST API. Learn about limitations and potential errors to avoid in your GitHub Actions workflows.

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

---

**When `actions/checkout` falls back to the GitHub REST API due to a missing or outdated Git executable, it explicitly does not support submodules and throws an error if the `submodules` input is enabled.**

The `actions/checkout` action is the standard mechanism for fetching repository code in GitHub Actions workflows. While the action typically prefers using a local Git installation, it can transparently fall back to downloading the repository via the GitHub REST API when Git is unavailable. However, this fallback path cannot handle **submodules** because it lacks the executable Git commands required to resolve nested repository pointers.

## How Repository Acquisition Works

The decision between Git-based cloning and REST API downloading occurs in [`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts). According to the source code at lines 77-84, the action first attempts to initialize a `GitCommandManager`. If this returns `null`—indicating Git is not installed or the version is below `gitCommandManager.MinimumGitVersion`—the action switches to the REST API download strategy.

This architectural split is critical because the REST API delivers a static archive (tarball or zip) of the repository at a specific commit, while Git-based cloning provides the full object database and metadata required for submodule operations.

## Why Submodules Require Local Git

Submodules cannot function without local Git executables for two technical reasons rooted in the source implementation.

First, the GitHub REST API provides only the files at a specific commit; it does not include `.gitmodules` configuration or submodule pointer hashes in a way that allows recursive fetching. Second, initializing and updating submodules requires executing specific Git commands. In [`src/git-command-manager.ts`](https://github.com/actions/checkout/blob/main/src/git-command-manager.ts) (lines 435-469), the action implements submodule handling through methods like `submoduleSync()` and `submoduleUpdate()`, which internally execute `git submodule sync` and `git submodule update --init --recursive`. Without a local Git binary, these commands cannot run.

## Input Validation and Error Handling

To prevent silent failures that would result in incomplete checkouts, the action implements a **fail-fast** validation mechanism.

In [`src/input-helper.ts`](https://github.com/actions/checkout/blob/main/src/input-helper.ts) (lines 144-151), the `submodules` input is parsed into a boolean flag (`true` when set to `"true"` or `"recursive"`). Before executing the REST API download path, [`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts) (lines 83-86) explicitly checks `settings.submodules`. If the value is `true`, the action throws an error with the message: *"Input 'submodules' not supported when falling back to download using the GitHub REST API..."*

This ensures that workflows requiring submodules do not proceed with broken partial checkouts.

## Ensuring Submodule Support in Your Workflows

To use submodules, you must ensure the runner has a sufficient Git version available in the `PATH`. The action requires Git ≥ `gitCommandManager.MinimumGitVersion` to enable the Git-based code path.

### Correct Usage with Git Available

```yaml
steps:
  - uses: actions/checkout@v4
    with:
      submodules: true
      token: ${{ secrets.GITHUB_TOKEN }}

```

This configuration works because the action detects the Git executable and executes the submodule commands defined in [`src/git-command-manager.ts`](https://github.com/actions/checkout/blob/main/src/git-command-manager.ts).

### Error Case When Git Is Missing

If Git is unavailable or too old, enabling submodules triggers an explicit failure:

```yaml
steps:
  - uses: actions/checkout@v4
    with:
      submodules: true
  # ❌ Error: "Input 'submodules' not supported when falling back to download 

  #    using the GitHub REST API. Submodules require Git to be installed..."

```

To resolve this error, install a recent Git version on the runner before the checkout step.

## Summary

- **No submodule support** exists when `actions/checkout` falls back to the GitHub REST API download method.
- The action validates the `submodules` input in [`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts) and throws an explicit error if submodules are requested without Git available.
- Submodules require local Git commands (`git submodule sync`, `git submodule update`) implemented in [`src/git-command-manager.ts`](https://github.com/actions/checkout/blob/main/src/git-command-manager.ts) (lines 435-469).
- Ensure Git ≥ `MinimumGitVersion` is in the runner's `PATH` to enable submodule functionality.

## Frequently Asked Questions

### What Git version is required for submodule support in actions/checkout?

The action requires a Git version equal to or greater than the `MinimumGitVersion` constant defined in the source code (typically Git 2.28 or newer in recent versions). You can verify your runner's Git version with `git --version` before the checkout step.

### Can I use submodules if the runner doesn't have Git installed?

No. If Git is not installed or is too old, `actions/checkout` falls back to the REST API, which cannot fetch submodules. The action will fail with an explicit error stating that submodules are not supported in REST API fallback mode. You must install Git on self-hosted runners to use this feature.

### What error message appears when using submodules without Git?

The action throws: *"Input 'submodules' not supported when falling back to download using the GitHub REST API. Submodules require Git to be installed."* This error originates from [`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts) (lines 83-86) and prevents the workflow from continuing with an incomplete repository state.

### Does the REST API fallback support recursive submodules?

No. The REST API fallback does not support submodules in any configuration—neither simple (`submodules: true`) nor recursive (`submodules: recursive`). Any submodule setting triggers the validation error because the REST API delivers a flat archive containing no submodule metadata or nested repository content.