Does actions/checkout Support SSH Keys with the REST API Fallback?

actions/checkout does not support SSH keys when falling back to the GitHub REST API, and the action aborts with an explicit error if you attempt to use an ssh-key input without a native Git client available.

When using the popular actions/checkout GitHub Action to clone repositories, you can authenticate via SSH keys using the ssh-key input. However, this authentication method is strictly tied to the native Git protocol implementation. If the runner environment lacks a compatible Git binary, the action falls back to downloading the repository via the GitHub REST API—a path that explicitly rejects SSH credentials and requires token-based authentication instead.

How actions/checkout Chooses Between Git and REST API

The action first checks for a Git client on the runner. When it detects a Git binary version 2.18 or higher, it proceeds with standard Git operations including SSH authentication. If no suitable Git client exists, the code executes a REST-API download path that fetches the repository as a tarball rather than cloning it.

In dist/index.js, the logic branches based on Git availability around lines 41748-41756. When the native Git path is unavailable, the action enters a fallback block that validates inputs differently than the standard Git workflow.

The SSH Key Validation Logic in dist/index.js

Inside the REST-API fallback block, the code explicitly checks for the presence of an sshKey setting and throws a fatal error to prevent unsupported authentication attempts:

else if (settings.sshKey) {
    throw new Error(`Input 'ssh-key' not supported when falling back to download using the GitHub REST API. To create a local Git repository instead, add Git ${MinimumGitVersion} or higher to the PATH.`);
}

This validation ensures that workflows failing to meet the Git version requirement do not attempt to pass sensitive SSH credentials through an incompatible transport mechanism. The ${MinimumGitVersion} variable evaluates to 2.18, making that the absolute minimum required to use SSH keys with this action.

Configuring Workflows for SSH Key Compatibility

To successfully use SSH authentication, you must ensure the runner has Git 2.18+ installed before the checkout step executes. Without this prerequisite, the action cannot establish an SSH connection to your repository.

Verify Git Version Requirements

Always confirm that your runner image includes Git 2.18 or later. Standard GitHub-hosted runners include recent Git versions, but self-hosted runners or minimal container images may require explicit installation steps.

Installing a Compatible Git Client

If your environment lacks the required Git version, install it prior to running actions/checkout:

steps:
  - name: Install Git (>= 2.18)
    run: |
      sudo apt-get update
      sudo apt-get install -y git
  - uses: actions/checkout@v7
    with:
      ssh-key: ${{ secrets.SSH_DEPLOY_KEY }}
      ssh-known-hosts: github.com

This ensures the action detects the native Git client and routes authentication through SSH rather than attempting the unsupported REST-API fallback.

Standard SSH Key Configuration

When Git is properly installed, configure the action to use your deploy key:

steps:
  - uses: actions/checkout@v7
    with:
      ssh-key: ${{ secrets.SSH_DEPLOY_KEY }}
      ssh-known-hosts: github.com
      persist-credentials: true

The persist-credentials option retains the SSH key for subsequent Git commands in the same job.

Error Scenario: Missing Git with SSH Key

Removing Git from the path while providing an SSH key triggers the explicit error:

steps:
  - name: Remove Git from PATH
    run: |
      sudo apt-get remove -y git
  - uses: actions/checkout@v7
    with:
      ssh-key: ${{ secrets.SSH_DEPLOY_KEY }}

This workflow fails immediately with the message: Input 'ssh-key' not supported when falling back to download using the GitHub REST API.

Key Source Files

The implementation details reside in these critical files within the actions/checkout repository:

• dist/index.js – Contains the core logic that determines whether to use native Git or REST-API download, including the SSH key validation that throws errors during fallback scenarios.
• README.md – Documents the ssh-key input and notes regarding the REST-API fallback behavior.
• action.yml – Defines the action inputs including ssh-key and ssh-known-hosts exposed to workflow authors.

Summary

• SSH keys require native Git: The ssh-key input only functions when actions/checkout uses the native Git protocol, not the REST-API fallback.
• Git 2.18 is mandatory: The action requires Git version 2.18 or higher to avoid the REST-API fallback and enable SSH authentication.
• Explicit error handling: If you provide an SSH key without a compatible Git client, dist/index.js throws a clear error and aborts the workflow.
• Install Git first: On minimal runners or containers, explicitly install Git before the checkout step to ensure SSH compatibility.

Frequently Asked Questions

What happens if I provide an SSH key but Git is not installed?

The action detects the missing Git client and enters the REST-API fallback path. When it encounters the ssh-key input in this state, it immediately throws an error stating that SSH keys are not supported when falling back to the GitHub REST API, and the workflow run fails.

What is the minimum Git version required for SSH key support in actions/checkout?

Git version 2.18 is the minimum required version. The source code defines this as MinimumGitVersion and uses it both to determine whether to use the native Git protocol and to recommend installation instructions when throwing compatibility errors.

Can I use SSH keys with the REST API fallback if I configure ssh-known-hosts?

No. The REST-API fallback fundamentally cannot use SSH keys regardless of ssh-known-hosts configuration. This fallback downloads the repository as a tarball via HTTPS using the GitHub API, which supports only token-based authentication. SSH keys require the Git protocol and a local Git repository initialization.

How do I prevent the REST API fallback to ensure SSH keys work?

Ensure Git 2.18 or higher exists in the runner's PATH before the checkout step executes. On self-hosted runners or minimal containers, add an explicit installation step using your package manager (apt, yum, apk, etc.) to install the git package prior to running actions/checkout.

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