How to Add SSH Keys for Deploys in CircleCI

The add_ssh_keys step loads a key you registered with the project into the job's SSH agent, so scp, rsync, or git over SSH can authenticate.

Add the private key under the project's SSH Keys settings, then reference its fingerprint in an add_ssh_keys step. The matching public key goes on the server or repo you are reaching.

Steps

• Add the private key in Project Settings to SSH Keys and copy its fingerprint.
• Add - add_ssh_keys with the fingerprints list to the deploy job.
• Use the key with ssh, scp, rsync, or git operations against a private host.

Config

version: 2.1
jobs:
  deploy:
    docker:
      - image: cimg/base:2024.02
    steps:
      - checkout
      - add_ssh_keys:
          fingerprints:
            - "SO:ME:FI:NG:ER:PR:IN:T0"
      - run: ssh -o StrictHostKeyChecking=accept-new deploy@app.example.com './pull-and-restart.sh'
workflows:
  ship:
    jobs:
      - deploy:
          filters:
            branches:
              only: main

Gotchas

• The fingerprint must match a key registered on the project; a wrong or missing one yields permission denied (publickey).
• First contact with a new host needs a known_hosts entry; use StrictHostKeyChecking=accept-new or pre-seed ~/.ssh/known_hosts.

Related guides