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

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 (lines 37-42) as a free-form string. In 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 (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 (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:

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

# .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 and constructs a temporary trust store in 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 (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.

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