# Understanding the ssh-known-hosts Input in actions/checkout

> Learn how to use the ssh-known-hosts input in actions/checkout to securely clone repositories over SSH from non-GitHub.com servers. Trust additional SSH host keys with ease.

- Repository: [GitHub Actions/checkout](https://github.com/actions/checkout)
- Tags: deep-dive
- Published: 2026-08-29

---

**The `ssh-known-hosts` input lets you provide additional SSH host keys that the checkout action will trust when cloning repositories over SSH from servers other than GitHub.com.**

When you use `actions/checkout` to access private repositories via SSH, the action must verify the server's identity using cryptographic host keys. By default, the action only trusts the public key for `github.com`. If your workflow connects to GitHub Enterprise Server or self-hosted Git instances, you must supply the appropriate host keys through the `ssh-known-hosts` input to establish verified connections without disabling security checks.

## How the ssh-known-hosts Input Works

The input is processed through a three-stage pipeline that constructs a temporary trust store for the duration of the checkout step.

### Input Definition and Retrieval

The `ssh-known-hosts` input is declared in [`action.yml`](https://github.com/actions/checkout/blob/main/action.yml) (lines 37-42) as a free-form string. In [`src/input-helper.ts`](https://github.com/actions/checkout/blob/main/src/input-helper.ts), the action retrieves the value at lines 161-162, accepting a multi-line string containing standard SSH `known_hosts` format entries. This allows you to specify multiple hosts and key types in a single declaration.

### Building the Temporary Known Hosts File

The core logic resides in [`src/git-auth-helper.ts`](https://github.com/actions/checkout/blob/main/src/git-auth-helper.ts) (lines 291-299). When preparing SSH authentication, the action constructs a temporary `known_hosts` file in the runner's temp directory:

1. **Preserve existing trust** – The action first copies entries from the user's global `~/.ssh/known_hosts` file, respecting the runner's baseline configuration.
2. **Append custom keys** – It writes the contents of the `ssh-known-hosts` input to the temporary file, adding your custom server keys.
3. **Include GitHub's key** – Finally, it always appends the public key for `github.com`, ensuring the action can still reach GitHub-hosted repositories.

The path to this generated file is stored in the action state via [`src/state-helper.ts`](https://github.com/actions/checkout/blob/main/src/state-helper.ts) (lines 26-28) under the key `sshKnownHostsPath`, enabling proper cleanup after the step completes.

### Injecting into Git Operations

The action constructs a custom `GIT_SSH_COMMAND` environment variable that includes:

```bash
-o "UserKnownHostsFile=$RUNNER_TEMP/<generated_file>"

```

This ensures Git uses the temporary trust store exclusively for the clone or fetch operation, without modifying the runner's permanent SSH configuration.

## Security Design and Strict Checking

Supplying custom host keys through `ssh-known-hosts` does **not** disable host-key verification. When `ssh-strict` remains `true` (the default), the action appends additional SSH options:

- `-o StrictHostKeyChecking=yes`
- `-o CheckHostIP=no`

This maintains strict host-key verification while allowing connections to succeed against your explicitly trusted servers. This approach avoids the unsafe "trust any host" pattern and ensures cryptographic verification of the server identity against your provided keys.

## Practical Configuration Example

The following workflow demonstrates checking out a repository from a self-hosted GitHub Enterprise instance:

```yaml

# .github/workflows/secure-checkout.yml

jobs:
  checkout-enterprise:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout from private enterprise server
        uses: actions/checkout@v4
        with:
          repository: my-org/internal-repo
          ssh-key: ${{ secrets.SSH_PRIVATE_KEY }}
          ssh-known-hosts: |
            # GitHub Enterprise Server host key

            gh-enterprise.example.com ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC...
            # Secondary internal Git server

            git.internal.example.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIE...
          ssh-strict: true
          persist-credentials: false

```

In this configuration:
- `ssh-key` provides the authentication credential
- `ssh-known-hosts` supplies the public identity keys for both custom servers
- `ssh-strict: true` enforces verification against these specific keys
- The action creates a temporary `known_hosts` file containing the runner's existing keys, your two supplied entries, and the implicit GitHub.com key

## Summary

- The `ssh-known-hosts` input accepts additional SSH host keys for servers other than GitHub.com, formatted as standard `known_hosts` entries.
- According to the `actions/checkout` source code, the action processes this input in [`src/input-helper.ts`](https://github.com/actions/checkout/blob/main/src/input-helper.ts) and constructs a temporary trust store in [`src/git-auth-helper.ts`](https://github.com/actions/checkout/blob/main/src/git-auth-helper.ts) (lines 291-299) by merging existing user keys, your custom keys, and GitHub's default key.
- The temporary file path is managed through [`src/state-helper.ts`](https://github.com/actions/checkout/blob/main/src/state-helper.ts) (lines 26-28) and injected into `GIT_SSH_COMMAND` for the duration of the Git operation.
- This mechanism preserves strict host-key checking while allowing verified connections to GitHub Enterprise and self-hosted Git servers.

## Frequently Asked Questions

### What happens if I don't provide ssh-known-hosts for a non-GitHub server?

If you attempt to clone from a server not in the default `known_hosts` and omit the `ssh-known-hosts` input, the SSH connection will fail with a host key verification error. The action only implicitly trusts `github.com`; all other hosts require explicit key declarations to pass strict verification checks.

### Does ssh-known-hosts replace the existing known_hosts file?

No, the input augments rather than replaces your existing configuration. The action copies entries from `~/.ssh/known_hosts` into a temporary file, appends your `ssh-known-hosts` entries, and uses this merged copy only for the current step. Your runner's global SSH configuration remains unchanged.

### Can I use ssh-known-hosts with ssh-strict set to false?

Yes, but this is not recommended. While the input still populates the temporary `known_hosts` file, setting `ssh-strict: false` disables `StrictHostKeyChecking`, which bypasses host-key verification entirely. You should keep `ssh-strict: true` (default) to ensure the keys you provide are actually validated against the server.

### How do I obtain the correct host key for my Git server?

Run `ssh-keyscan -t rsa,ed25519 your-git-server.example.com` from a trusted network location to retrieve the server's public keys. Verify the output against your server's documentation or administrator before adding it to the `ssh-known-hosts` input to prevent man-in-the-middle attacks.