> For the complete documentation index, see [llms.txt](https://circleci.com/docs/llms.txt)

# Add additional SSH keys to CircleCI

Add additional SSH keys to your project for access to deploy to other services, or to write or check out code from other repositories.

If you want to set up an SSH key in order to checkout code from additional repositories in GitHub or Bitbucket Cloud and you have a `github` or `bitbucket` organization, see the [Users, Organizations, and Integrations Guide](https://circleci.com/docs/guides/permissions-authentication/users-organizations-and-integrations-guide/#create-a-user-key) for steps to add a user key. Alternatively follow steps on this page to add additional SSH keys to your project.

You may need to add the public key to `~/.ssh/authorized_keys` in order to add SSH keys.

See the following VCS-specific docs for additional details on creating SSH keys:

*   [GitHub](https://help.github.com/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent/)
    
*   [Bitbucket](https://support.atlassian.com/bitbucket-cloud/docs/configure-ssh-and-two-step-verification/)
    
*   [GitLab](https://docs.gitlab.com/ee/user/ssh.html)
    

## Add an additional SSH key to your project

CircleCI cannot decrypt SSH keys, therefore every new key must have an empty passphrase. The below examples are for macOS.

1.  In the [CircleCI web app](https://app.circleci.com), select your org from the org cards on your user homepage.
    
2.  Select **Projects** from the sidebar and locate your project from the list. You can use the search to help.
    
3.  Select the ellipsis next to your project and select **Project Settings**.
    
    You can also access project settings from each project overview page using the **Settings** button.
    

4.  In the sidebar menu, select **SSH Keys**.
    
5.  Scroll down to the **Additional SSH Keys** section.
    
    If you have a GitLab integration, you will find that an additional SSH key already exists. This was created automatically by CircleCI during the project creation process. This key is used to check out your code so it should not be removed.
    
6.  Select **Add SSH Key**.
    
7.  In the **Hostname** field, enter the key’s associated host (for example, `git.heroku.com`). If you do not specify a hostname, the key will be used for all hosts.
    
8.  In the **Private Key** field, paste the SSH key you are adding.
    
9.  Select **Add SSH Key**.
    

## Add SSH keys to a job

Even though all CircleCI jobs use `ssh-agent` to automatically sign all added SSH keys, you **must** use the `add_ssh_keys` key to actually add keys to a container.

To add a set of SSH keys to a container, use the `add_ssh_keys` [special step](https://circleci.com/docs/reference/configuration-reference/#add-ssh-keys) within the appropriate [job](https://circleci.com/docs/guides/orchestrate/jobs-steps/) in your configuration file. The fingerprint can be SHA256 or MD5. SHA256 fingerprints should be prefixed with `SHA256:` and MD5 fingerprints should include the colons between character pairs. When you add your key to CircleCI in **Project Settings**  **SSH keys**  **Additional SSH keys** the SHA256 fingerprint will be visible.

**Using server?** Only MD5 fingerprints are supported. In CircleCI in **Project Settings**  **SSH keys**  **Additional SSH keys** the MD5 fingerprint will be visible. SHA256 support is planned for an upcoming server release.

For a self-hosted runner, ensure that you have an `ssh-agent` on your system to successfully use the `add_ssh_keys` step. The SSH key is written to `$HOME/.ssh/id_rsa_<fingerprint>`, where `$HOME` is the home directory of the user configured to execute jobs, and `<fingerprint>` is the MD5 fingerprint of the key. A host entry is also appended to `$HOME/.ssh/config`, along with a relevant `IdentityFile` option to use the key.

```yaml
jobs:
  deploy-job:
    docker:
      - image: cimg/base:2022.09
    steps:
      - add_ssh_keys:
          fingerprints:
            - "SO:ME:FIN:G:ER:PR:IN:T"
            - "SHA256:NPj4IcXxqQEKGXOghi/QbG2sohoNfvZ30JwCcdSSNM0"
```

All fingerprints in the `fingerprints` list must correspond to keys that have been added through the CircleCI application. Fingerprints in CircleCI environment variables will fail.

To check out additional repositories from within your job, ensure that you run the `checkout` command **before** `add_ssh_keys`; otherwise, `CIRCLE_CI_REPOSITORY_URL` will be empty. Also ensure that the private key is added to the CircleCI project and that the public key has been added to the additional repositories that you want to check out from within your job.

### Adding multiple keys with blank hostnames

If you add multiple SSH keys with blank hostnames to your project, you will need to make some changes to the default SSH configuration provided by CircleCI.

If you have multiple SSH keys for different purposes that have access to the same hosts, the default `IdentitiesOnly no` is set, which causes connections to use `ssh-agent`.

In this scenario the first key is used regardless of whether it is the correct key. If you have added the SSH key to a container, you will need to either set `IdentitiesOnly yes` in the appropriate block, or you can remove all keys from the `ssh-agent` for the job using `ssh-add -D` and read the added key using `ssh-add /path/to/key`.

### Using specific SSH keys for a job

SSH keys are named using MD5 fingerprints with colons removed from the hash.

To retrieve the MD5 fingerprint of an SSH key, run this command locally:

`ssh-keygen -l -E md5 -f ~/.ssh/your_key_name`

The filename follows this format:

`id_rsa_[MD5_fingerprint_without_colons]`

Example:

*   SSH key MD5 fingerprint: `a3:f9:82:c5:1d:47:9b:e6:88:32:a1:bc:f4:29:7e:15`.
    
*   SSH key filename: `id_rsa_a3f982c51d479be68832a1bcf4297e15`.
    

If you have added multiple SSH keys for the same hostname to your project and want to use a specific key in your SSH commands, follow these steps:

1.  Add the SSH key to the job using the `add_ssh_keys` step.
    
2.  Use the `-i` parameter to specify the exact SSH key file path in your SSH commands.
    
3.  Add the `-o "IdentitiesOnly=yes"` option to prevent SSH from using other keys from the SSH agent.
    

Example:

```bash
ssh -i ~/.ssh/id_rsa_a3f982c51d479be68832a1bcf4297e15 -o "IdentitiesOnly=yes" user@hostname
```