CircleCI checkout "Permission denied (publickey)" - Fix Keys

The checkout step cannot authenticate to the Git host over SSH. The project’s checkout/deploy key is missing or wrong, or the clone touches a private submodule the key cannot read - so the clone is refused.

What this error means

The job fails at checkout with "Permission denied (publickey)" and "Could not read from remote repository". The repo is private (or has private submodules) and the SSH key CircleCI presented was rejected.

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

Common causes

No checkout key configured for the project

CircleCI clones via an SSH key set up in Project Settings. If the deploy/checkout key was never added or was revoked on the host, the clone is denied.

Private submodules the key cannot read

The checkout key grants access to the main repo, but git submodule update against a different private repo needs additional access (a user key or extra deploy key).

Wrong or rotated additional SSH key

An add_ssh_keys fingerprint that no longer matches a configured key, or a rotated host key, makes authentication fail.

How to fix it

Add the SSH key and check out, including submodules

jobs:
  build:
    docker: [{ image: cimg/base:current }]
    steps:
      - add_ssh_keys:
          fingerprints:
            - "SO:ME:FINGER:PR:IN:T"
      - checkout
      - run: git submodule sync && git submodule update --init

Provision project access correctly

1. Confirm Project Settings → SSH Keys has a valid checkout/deploy key for the repo.
2. For private submodules, add a user key (or per-submodule deploy keys) with read access.
3. Match add_ssh_keys fingerprints to keys that still exist on the host.

How to prevent it

• Keep a valid checkout key in Project Settings, rotated in sync with the host.
• Grant submodule access explicitly (user key or per-repo deploy keys).
• Track add_ssh_keys fingerprints so rotations do not silently break checkout.

Related guides