What Happens if Git Is Unavailable in actions/checkout: Fallback Behavior Explained

If Git is unavailable or below version 2.18, actions/checkout automatically falls back to downloading the repository as a compressed archive via the GitHub REST API, disabling Git-specific features like submodules, SSH authentication, and LFS.

The actions/checkout action is the standard way to clone repositories in GitHub Actions workflows. While it assumes a Git binary is present on the runner, the codebase includes robust fallback logic to handle environments where Git is missing or outdated, ensuring workflows can still retrieve source code.

How actions/checkout Detects a Missing Git Installation

The detection logic resides in src/git-source-provider.ts. When the action initializes, it attempts to instantiate a GitCommandManager to verify Git availability and version compatibility. If GitCommandManager.create() returns undefined—either because Git is not in the PATH or the installed version is below the MinimumGitVersion (2.18)—the code enters the fallback path.

In src/git-command-manager.ts, the action explicitly defines the minimum supported version as 2.18. If the runner fails this version check, the provider immediately switches strategies rather than failing the job.

The REST API Fallback Mechanism

When Git is unavailable, actions/checkout retrieves the repository via the GitHub REST API using githubApiHelper.downloadRepository (implemented in src/github-api-helper.ts). This downloads the repository as a .zip or .tar.gz archive and extracts it directly into the workspace (settings.repositoryPath).

Because this method produces a plain file tree without any Git metadata, the resulting directory contains no .git folder. This means subsequent steps that rely on Git commands—such as git log, git rev-parse, or git status—will fail unless they implement similar fallback logic.

Feature Limitations When Git Is Unavailable

Without a local Git repository, several inputs become unsupported. The action logs specific warnings for each disabled feature via src/input-helper.ts.

Submodules

The submodules input is not supported in fallback mode. When specified in a workflow running without Git, the action prints a warning that submodule handling is unavailable because the REST API download provides only the main repository contents.

SSH Authentication

The ssh-key input cannot be used when falling back to the API download. SSH authentication requires a local Git client to handle key negotiation and transport protocols. In src/git-source-provider.ts, the code skips SSH setup when the Git provider is unavailable, directing users to alternatively configure HTTPS tokens or OIDC.

Sparse Checkout and Git LFS

Sparse checkout and Git LFS (Large File Storage) features are disabled. These capabilities require Git's filtering and smudge/clean filters, which are impossible to execute without the Git binary. The action treats these inputs as no-ops and logs appropriate warnings.

User Warnings and Safety Checks

Even when using the API fallback, the action maintains environment consistency. The code emits a clear warning prompting users to install Git:

To create a local Git repository instead, add Git 2.18 or higher to the PATH

Additionally, src/git-source-provider.ts attempts to set the repository path as a safe directory in the global Git config (lines 51-54), even though Git isn't used for the checkout. This ensures that if Git is installed later in the workflow, subsequent commands won't trigger "dubious ownership" errors.

Practical Example: Simulating Git Unavailability

You can observe this behavior by intentionally removing Git from a runner before invoking the checkout action:

name: Test Git Fallback
on: [push]

jobs:
  checkout-without-git:
    runs-on: ubuntu-latest
    steps:
      - name: Remove Git to simulate unavailable binary
        run: sudo apt-get remove -y git
      
      - uses: actions/checkout@v4
        with:
          submodules: true
        # Expected warnings:

        # 1. "To create a local Git repository instead, add Git 2.18 or higher to the PATH"

        # 2. "Input 'submodules' not supported when falling back to download using the GitHub REST API."

      
      - name: Verify no .git directory exists
        run: |
          if [ -d ".git" ]; then
            echo "Git repository found (unexpected)"
          else
            echo "No .git directory - using API fallback"
          fi

Summary

• Graceful degradation: When Git is unavailable or below version 2.18, actions/checkout falls back to downloading the repository as a .zip or .tar.gz archive via the GitHub REST API.
• No Git metadata: The fallback creates a plain file tree without a .git directory, breaking any subsequent Git-dependent steps.
• Disabled features: Submodules, SSH keys, sparse checkout, and LFS are unsupported in fallback mode and generate warnings.
• Safety maintained: The action still configures the workspace as a safe directory for potential future Git operations.

Frequently Asked Questions

Will my workflow fail if Git is not installed on the runner?

No, the workflow will not fail. According to the actions/checkout source code in src/git-source-provider.ts, the action detects the missing binary and automatically switches to downloading the repository via the GitHub REST API. However, any steps that require Git commands will fail unless you install Git after the checkout step.

Can I use submodules without Git installed?

No, submodules require a local Git client to clone and initialize nested repositories. The code in src/input-helper.ts explicitly checks for Git availability and logs a warning that submodules are not supported when falling back to the API download method. You must install Git 2.18 or higher and ensure it is in the PATH before the checkout action runs.

Does the REST API fallback preserve the Git history?

No, the fallback downloads only the current snapshot of the repository as a compressed archive. Because githubApiHelper.downloadRepository extracts the files without initializing a Git repository, there is no .git directory and no commit history. Commands like git log will return "not a git repository" errors.

What is the minimum Git version required for full functionality?

The action requires Git 2.18 or higher for full functionality. This minimum version is defined in src/git-command-manager.ts as MinimumGitVersion. Versions below this threshold trigger the API fallback, disabling features that require modern Git capabilities like partial clones or improved submodule handling.

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