Adding an SSH Key to CircleCI
If deploying to your servers requires SSH access, you’ll need to add SSH keys to CircleCI.
Overview
There are two reasons to add SSH keys to CircleCI:
- To check out code from version control systems.
- To enable running processes to access other services.
If you are adding an SSH key for the first reason, refer to the GitHub and Bitbucket Integration document. Otherwise, follow the steps below to add an SSH key to your project.
Steps
-
In a terminal, generate the key with
ssh-keygen -m PEM -t rsa -C "your_email@example.com". See the (SSH) Secure Shell documentation web site for additional details. -
In the CircleCI application, go to your project’s settings by clicking the the Project Settings button (top-right on the Pipelines page of the project).
-
On the Project Settings page, click on SSH Keys (vertical menu on the left).
-
Scroll down to the Additional SSH Keys section.
-
Click the Add SSH Key button.
-
In the Hostname field, enter the key’s associated host (for example, “git.heroku.com”). If you don’t specify a hostname, the key will be used for all hosts.
-
In the Private Key field, paste the SSH key you are adding.
-
Click the Add SSH Key button.
Note:
Since CircleCI cannot decrypt SSH keys,
every new key must have an empty passphrase.
CircleCI also will not accept OpenSSH’s default file format - use ssh-keygen -m pem if you are using OpenSSH to generate your key.
Caution: Recent updates in ssh-keygen don’t generate the key in PEM format by default. If your private key does not start with -----BEGIN RSA PRIVATE KEY-----, enforce PEM format by generating the key with ssh-keygen -m PEM -t rsa -C "your_email@example.com"
Adding 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.
version: 2
jobs:
deploy-job:
steps:
- add_ssh_keys:
fingerprints:
- "SO:ME:FIN:G:ER:PR:IN:T"
Note:
All fingerprints in the fingerprints list
must correspond to keys
that have been added through the CircleCI application.
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 hostss, 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.