Managing Your SSH Keys

Last updated 06 May 2019

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.

In order to run these commands on a Windows machine, run the Git Bash application. 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 adam@workstation.local

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 heroku keys:add.

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_rsa.pub or ~/.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 adam@workstation.local
Removing adam@workstation.local 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 heroku keys:clear.

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
=== joe@example.com Keys
ssh-dss AAAAB8NzaC...DVj3R4Ww== adam@workstation.local

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 git@heroku.com

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 ([50.19.85.156]: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.

Feedback

Log in to submit feedback.