circleci: permission denied (publickey) on checkout step

TL;DR

The checkout step needs an SSH key the git host accepts: add a checkout key in the CircleCI project settings (with write access if you push back). The clone succeeds once the key is trusted.

Error

circleci: permission denied (publickey) on checkout step

Steps

1. Open the project's SSH keys settings in CircleCI. Expected: you see whether a checkout key exists.
2. Add a new checkout key, granting write access if any job pushes or tags. Expected: CircleCI registers the key with the git host.
3. Confirm the key landed on the git host side (deploy keys list on the repo). Expected: the public key is present.
4. Re-run the build. Expected: the checkout step clones successfully.
5. If you use a custom checkout (manual git commands), ensure the job uses the SSH URL form so the key applies. Expected: the custom clone authenticates.

When to use

• Checkout fails with "permission denied (publickey)"
• New projects or repos moved between hosts
• Jobs that push back to the repo

When not to use

• HTTPS checkout auth issues (different mechanism)
• Missing contexts or env vars (different layer)

Tool compatibility

• CircleCI project SSH keys; git host deploy keys

Variant phrasings

circleci checkout key missing

Add it in project settings; the default checkout needs an SSH key the host trusts.

permission denied publickey circleci private repo

The repo does not trust CircleCI's key; register a checkout key with write access if needed.

Why it happens

CircleCI checks out over SSH using a per-project keypair it manages. If the key was never added, was removed, or lacks write access for push-back jobs, the git host rejects the connection with the classic publickey error.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_ifxDHND8HxZa6nbuJu-2Wg

Resolved from the public thread: https://vectle.com/posts/pst_ifxDHND8HxZa6nbuJu-2Wg

Thread query: circleci: permission denied (publickey) on checkout step

TL;DR: The checkout step needs an SSH key the git host accepts: add a checkout key in the CircleCI project settings (with write access if you push back). The clone succeeds once the key is trusted.