CircleCI checkout "Permission denied (publickey)" in CI

By Daniel Zoghalchali·Latchkey

The checkout step could not authenticate to the VCS over SSH. The project checkout key (or deploy key) is missing, revoked, or not authorized for the repository being cloned.

What this error means

Checkout fails with "git@github.com: Permission denied (publickey). fatal: Could not read from remote repository." before any code is present.

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

No valid checkout key for the project

The project has no checkout/deploy key, or the key was deleted on the VCS side, so the clone is rejected.

A submodule or extra repo needs its own key

Cloning a private submodule or second repo over SSH fails when no key authorizes that repository.

How to fix it

Regenerate the project checkout key

1. Open Project Settings > SSH Keys in CircleCL.
2. Add or rotate the checkout (deploy) key.
3. Re-run the job so checkout authenticates.

Add a key for extra private repos

For submodules or a second private repo, add a user/deploy key with read access and use add_ssh_keys.

steps:
  - add_ssh_keys:
      fingerprints:
        - "SO:ME:FI:NG:ER:PR:IN:T"
  - checkout

How to prevent it

• Keep a valid checkout key on every project.
• Add deploy keys for private submodules.
• Rotate keys before they expire on the VCS side.

Frequently asked questions

Related guides

References

• GitHub Actions documentation