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

> actions/checkout does not support SSH keys with REST API fallback. Learn why the action aborts and how to avoid errors with your Git operations.

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

---

**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`](https://github.com/actions/checkout/blob/main/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:

```javascript
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`:

```yaml
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:

```yaml
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:

```yaml
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`](https://github.com/actions/checkout/blob/main/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`](https://github.com/actions/checkout/blob/main/README.md)** – Documents the `ssh-key` input and notes regarding the REST-API fallback behavior.
- **[`action.yml`](https://github.com/actions/checkout/blob/main/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`](https://github.com/actions/checkout/blob/main/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`.