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

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. 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 (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 (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 (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

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.

Error Case When Git Is Missing

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

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 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 (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 (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.

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