How to fix Permission denied (publickey). CircleCI checkout key may be invalid or revoked in Git

First, verify what SSH keys CircleCI is currently using for your project:

1. Go to your CircleCI project dashboard
2. Click Project Settings (gear icon)
3. Navigate to SSH Keys in the left sidebar
4. Look at the Checkout SSH Keys section

You'll see one of these key types:
- Deploy Key: Repository-specific, read-only access (recommended)
- User Key: Uses your personal GitHub account permissions

Note the Fingerprint shown - you'll need this to match it with GitHub.

If no checkout key is listed, that's the problem - continue to step 3 to add one.

Check if the corresponding public key exists in your repository:

For GitHub:
1. Go to your repository on GitHub
2. Click Settings > Deploy keys
3. Look for a key with fingerprint matching CircleCI's key

For GitLab:
1. Go to your project on GitLab
2. Click Settings > Repository > Deploy Keys
3. Verify the CircleCI key is listed and enabled

For Bitbucket:
1. Go to your repository on Bitbucket
2. Click Repository settings > Access keys
3. Check if the CircleCI key exists

If the key is missing from your repository but exists in CircleCI, the key needs to be re-added. Continue to step 4.

If CircleCI has an outdated or invalid key, remove it:

1. In CircleCI, go to Project Settings > SSH Keys
2. Under Checkout SSH Keys, find the problematic key
3. Click the X or Delete button next to the key
4. Confirm the deletion

Note: This will temporarily break builds until you add a new valid key.

Alternatively, use the CircleCI CLI or API:

# Using CircleCI CLI (if installed)
circleci project settings --delete-checkout-key <fingerprint>

Generate and add a new checkout key:

Option A: Let CircleCI generate the key (Recommended)

1. In CircleCI, go to Project Settings > SSH Keys
2. Scroll to Checkout SSH Keys
3. Click Add Deploy Key (or Create and add key)
4. CircleCI will automatically:
- Generate a new SSH key pair
- Add the public key to your GitHub repository as a deploy key
- Configure the private key for use in builds

Option B: Add a User Key (for private dependencies)

If your build needs to access multiple private repositories:

1. Click Add User Key instead
2. Authorize CircleCI to access your GitHub account
3. This grants access to all repositories your account can access

Warning: User keys have broader access. Prefer deploy keys for single-repository access.

For GitLab or Bitbucket:

CircleCI may not auto-add keys for non-GitHub repos. You'll need to:
1. Generate a key pair manually
2. Add the private key to CircleCI
3. Add the public key to your GitLab/Bitbucket repository

For GitLab, Bitbucket, or self-hosted Git:

Generate a new SSH key pair:

# Generate an Ed25519 key (recommended)
ssh-keygen -t ed25519 -C "circleci-deploy@your-project" -f circleci_key -N ""

# Or generate an RSA key for older systems
ssh-keygen -t rsa -b 4096 -C "circleci-deploy@your-project" -f circleci_key -N ""

This creates two files:
- circleci_key (private key)
- circleci_key.pub (public key)

Add the private key to CircleCI:

1. Go to Project Settings > SSH Keys
2. Click Add SSH Key under "Additional SSH Keys"
3. Enter your Git hostname (e.g., gitlab.com, bitbucket.org)
4. Paste the contents of circleci_key (private key)
5. Click Add SSH Key

Add the public key to your repository:

# Display the public key
cat circleci_key.pub

Copy this and add it as a deploy key in your repository settings.

Securely delete the local key files:

rm circleci_key circleci_key.pub

After adding the new key, trigger a new build:

1. Go to your CircleCI project dashboard
2. Click Rerun workflow from failed or Rerun from start
3. Watch the Checkout code step

Expected success:

Checkout code
  Using SSH Config
  Cloning into '.'...
  done.

If it still fails, check:
- The key fingerprint matches between CircleCI and your repository
- The deploy key has read access to the repository
- For private repos, ensure the key is not read-only if write access is needed

Verify SSH connectivity manually:

You can also test from a CircleCI shell:

# Add this step temporarily to your config.yml
- run:
    name: Debug SSH
    command: |
      ssh -T [email protected] || true
      ssh-add -l

For repositories in a GitHub Organization, additional steps may be required:

Enable OAuth App access:

1. Go to your GitHub Organization settings
2. Navigate to Third-party access > OAuth Apps
3. Find CircleCI and click Review
4. Ensure CircleCI has access to the repository

Request organization approval (if required):

If your organization restricts third-party access:
1. An organization admin must approve CircleCI's access
2. The admin can do this at: Organization Settings > Third-party access

Use SSH deploy keys instead of OAuth:

For stricter security requirements, use deploy keys:
1. Remove any user keys in CircleCI
2. Add a deploy key as described in step 4
3. Deploy keys are scoped to a single repository

Check organization SAML enforcement:

If your organization uses SAML SSO:
1. Ensure your SSH keys are authorized for SAML
2. Go to GitHub Settings > SSH and GPG keys
3. Click Configure SSO next to the relevant key
4. Authorize the key for your organization

If using a custom SSH key (not the default checkout key), update your .circleci/config.yml:

Using the add_ssh_keys step:

version: 2.1

jobs:
  build:
    docker:
      - image: cimg/base:stable
    steps:
      # Add custom SSH key before checkout
      - add_ssh_keys:
          fingerprints:
            - "SO:ME:FI:NG:ER:PR:IN:T0:12:34:56:78:90:ab:cd:ef"

      # Now checkout will use the added key
      - checkout

      - run:
          name: Build
          command: echo "Building..."

For accessing private dependencies:

steps:
  - add_ssh_keys:
      fingerprints:
        - "key-fingerprint-for-private-dep-repo"

  - checkout

  - run:
      name: Clone private dependency
      command: git clone [email protected]:org/private-lib.git

Find the fingerprint:

The fingerprint is shown in CircleCI under Project Settings > SSH Keys after you add the key.