CircleCI checkout "Permission denied (publickey)"

By Kaveh Alemi·Latchkey

The checkout step could not authenticate to the git remote over SSH. CircleCI has no valid checkout/deploy key for the repo, so the clone is refused.

What this error means

The checkout step fails immediately with "Permission denied (publickey)" and "Could not read from remote repository". No source is fetched, so every later step fails.

git@github.com: Permission denied (publickey).
fatal: Could not read from remote repository.
Please make sure you have the correct access rights and the repository exists.

Common causes

Missing or revoked checkout key

CircleCI uses a checkout/deploy key to clone. If it was never added, was revoked on the VCS side, or lacks access to the repo, the SSH handshake is rejected.

Submodule or extra repo needs its own key

The main repo clones fine, but a private submodule or a second repo accessed in a step has no key, so its fetch is denied with the same message.

How to fix it

Re-add the checkout/deploy key

1. In Project Settings - SSH Keys, confirm a checkout key exists with repo access.
2. If missing or revoked, add a new user/deploy key and re-authorize on the VCS.
3. Re-run; the checkout step should authenticate.

Add a key for submodules or extra repos

- add_ssh_keys:
    fingerprints:
      - "SO:ME:FI:NG:ER:PR:IN:T"
- run: git submodule update --init

How to prevent it

• Keep a valid checkout key with repo access in Project Settings.
• Add explicit SSH keys for private submodules and secondary repos.
• Rotate keys deliberately so checkout access is not silently lost.

Frequently asked questions

Related guides

References

• GitHub Actions documentation