Add additional SSH keys to CircleCI
Add additional SSH keys to your project for access to deploy other services or to write to, or checkout code from other repositories.
If you want to set up an SSH key in order to checkout code from additional repositories in GitHub ( GitHub OAuth app only) or Bitbucket Cloud within a job, refer to the GitHub OAuth app or Bitbucket Cloud integration pages. If you need additional SSH keys to access other services and your org is set up to the use GitHub OAuth app or Bitbucket Cloud, follow the steps below.
You may need to add the public key to ~/.ssh/authorized_keys in order to add SSH keys.
1. 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.
-
In a terminal, generate the key with
ssh-keygen -t ed25519 -C "your_email@example.com". See Secure Shell documentation for additional details. -
In the CircleCI application, go to your project’s settings by clicking the Project Settings button (top-right on the Pipelines page of the project).
-
On the Project Settings page, select SSH Keys.
-
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 checkout your code so it should not be removed.
-
Select Add SSH Key.
-
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. -
In the Private Key field, paste the SSH key you are adding.
-
Select Add SSH Key.
2. 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 within the appropriate job 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 the SHA256 fingerprint will be visible.
| Using server? Only MD5 fingerprints are supported. In CircleCI in 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.
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 checkout 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 checkout from within your job.
Adding multiple keys with blank hostnames
If you need to 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. In the scenario where you have multiple SSH keys that have access to the same hosts, but are for different purposes the default IdentitiesOnly no is set causing connections to use ssh-agent. This will always cause the first key to be used, even if that is the incorrect key. If you have added the SSH key to a container, you will need to either set IdentitiesOnly no in the appropriate block, or you can remove all keys from the ssh-agent for this job using ssh-add -D, and reading the key added with ssh-add /path/to/key.