Managing Your SSH Keys
Last updated 14 September 2018
If you wish to use SSH instead of the default HTTPS git transport, you’ll need to create a public/private key pair to deploy code. This keypair is used for the strong cryptography and that uniquely identifies you as a developer when pushing code changes.
Configuring SSH keys is only required if you want to use SSH Git transport when pushing to Heroku. Heroku uses HTTP Git transport by default, and if you’re happy with that, you can disregard the contents of this article.
SSO users can use SSH keys only for securing the SSH tunnels needed when
heroku run is used on apps in Shield Private Spaces but not for authentication (e.g. for
git push heroku master).
Heroku supports RSA and DSA key formats. ECDSA keys are currently not supported.
Git Bashapplication. A shortcut for this application should be on your desktop, installed as part of the Heroku CLI.
To generate a public key:
$ ssh-keygen -t rsa Generating public/private rsa key pair. Enter file in which to save the key (/Users/adam/.ssh/id_rsa): Enter passphrase (empty for no passphrase): Enter same passphrase again: Your identification has been saved in /Users/adam/.ssh/id_rsa. Your public key has been saved in /Users/adam/.ssh/id_rsa.pub. The key fingerprint is: a6:88:0a:0b:74:90:c6:e9:d5:49:d6:e3:04:d5:6c:3e email@example.com
Press enter at the first prompt to use the default file location. Next, type a secure passphrase for the key.
Adding keys to Heroku
Upload your key to heroku with
A common key error is:
Permission denied (publickey).
You can fix this by using
keys:add to notify Heroku of your new key. Or by using http-git.
If you wish to add other keys, use this command:
$ heroku keys:add Found existing public key: /Users/adam/.ssh/id_rsa.pub Uploading SSH public key /Users/adam/.ssh/id_rsa.pub... done
Without an argument, it will look for the key in the default place
~/.ssh/id_dsa.pub). If you wish to use an alternate
key file, specify it as an argument. Be certain you specify the public part of
the key (the file ending in .pub). The private part of the key should never be
transmitted to any third party, ever.
For security purposes Heroku will email you whenever a new SSH key is added to your account.
Revoke old keys you’re no longer using or that you think might be compromised (for example, if your workstation is lost or stolen):
$ heroku keys:remove firstname.lastname@example.org Removing email@example.com SSH key... done
If your key doesn’t have a name or its name is shared by another key, a key can also be removed by passing in some portion of its public key (e.g.
heroku keys:remove DVj3R4W). All keys on the account can be removed with
The key’s name is the
user@workstation bit that appears at the end of the key line
in your public key file. You can see a list of all keys, including the key’s
name, like this:
$ heroku keys === firstname.lastname@example.org Keys ssh-dss AAAAB8NzaC...DVj3R4Ww== email@example.com
The ASCII-armored key data is shortened for readability. If you wish to see the full public key, use the
--long argument. You will probably want to redirect this to a file (
heroku keys --long > keys.txt), since it will be easier to look at in a text editor.
Validate the connection
You can check to see whether your keys are working by trying the following command:
$ ssh -v firstname.lastname@example.org
You’ll get a large amount of output. If the connection was successful, you’ll see something like these messages buried in the text:
... debug1: Offering RSA public key: /Users/jonmountjoy/.ssh/id.heroku .... Authenticated to heroku.com ([18.104.22.168]:22). ...
If it was unsuccessful, you’ll see text that includes:
... debug1: Offering RSA public key: /Users/jonmountjoy/.ssh/github_rsa ... Permission denied (publickey).
Fixing problems with keys
One common source of SSH key problems is that Heroku has been configured with a key that’s different the key your
git command is offering to Heroku.
For example, if you get
Permission denied (publickey) - validate the connection and check which key is being offered to Heroku. It will typically be denoted by something like:
debug1: Offering RSA public key: /Users/jonmountjoy/.ssh/github_rsa
In this case the key we’ve previous generated for GitHub is being sent to Heroku, instead of the key we generated for Heroku.
You can modify the SSH mechanism to send a different key depending on the host by creating or modifying a
.ssh/config file. The following snippet will ensure that when SSH communicates with the
heroku.com domain, that our Heroku certificate is offered instead:
Host heroku.com HostName heroku.com IdentityFile /Users/jonmountjoy/.ssh/id.heroku IdentitiesOnly yes
This key is already in use by another account
If you get a
This key is already in use by another account, that means that the key you’re trying to upload has already been added to a different Heroku account, probably one that you created previously.
You should either log in with the old account and remove the pertinent key or create a new SSH key (with
ssh-keygen) to use with the new account.