Problem

During the checkout step, your build fails with the error: "Either git or ssh (required by git to clone through SSH) is not installed in the image". This occurs when your Docker image is missing git or openssh-client, which are required for CircleCI to check out your code.

Solutions

Verify Git and SSH Are Installed

Check if git and openssh-client are installed in your image by running these commands in a build step:

git --version
ssh -V

If these commands fail, the tools are missing and need to be installed.

Install Git and OpenSSH Client

Add a run step to install the required tools before the checkout step. The installation method depends on your base image's operating system.

For Debian-based images (Ubuntu, Debian):

- run: apt-get update && apt-get install -y openssh-client git

For Alpine-based images:

- run: apk add --update openssh-client git

Use CircleCI Convenience Images

CircleCI convenience images come with git, openssh-client, and other common CI/CD tools pre-installed. Using these images eliminates the need for manual installation.

Replace your current image with a CircleCI convenience image:

jobs:
  build:
    docker:
      - image: cimg/base:2024.12

CircleCI offers convenience images for many languages including Node.js, Python, Ruby, Go, and more. Find the right image for your project on the CircleCI Developer Hub.

Outcome

After installing git and openssh-client or switching to a CircleCI convenience image, the checkout step should complete successfully. Your build will proceed to clone your repository and continue with subsequent steps.

Additional Notes

CircleCI convenience images include git, Docker, Docker Compose, and other commonly used tools
Next-generation convenience images (prefixed with cimg/) are recommended over legacy images
Installing packages during the build adds time to your job - using pre-built images is more efficient