Last updated May 03, 2023

Configure SSH keys to enable tunneling (heroku ps:exec) for Private Spaces apps.

Generate an SSH Key

Generate a public-private key pair using ssh-keygen:

$ ssh-keygen -t ed25519
Generating public/private ed25519 key pair.
Enter file in which to save the key (/Users/adam/.ssh/id_ed25519):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /Users/adam/.ssh/id_ed25519.
Your public key has been saved in /Users/adam/.ssh/id_ed25519.pub.
The key fingerprint is:
SHA256:ZVZJqKLFasHmdPMoz5KTyd9jF3pCML8WAffYe3G5iDf adam@workstation.local

Press enter at the first prompt to use the default file location. Next, type a secure passphrase for the key.

Add Keys to a Heroku Account

Use the keys:add CLI command to upload one or more keys and associate them with your account. The Heroku CLI searches for keys in the default location and ask to upload them:

$ heroku keys:add
Found an SSH public key at /Users/adam/.ssh/id_ed25519.pub
? Would you like to upload it to Heroku? [Y/n]
Uploading /Users/adam/.ssh/id_ed25519.pub SSH key... done

Append the -y or --yes flag to keys:add to bypass the confirmation:

$ heroku keys:add --yes
Found an SSH public key at /Users/adam/.ssh/id_ed25519.pub
Uploading /Users/adam/.ssh/id_ed25519.pub SSH key... done

If the key is in an alternate location, specify the location when running the command. Declaring the path of the key also bypasses the confirmation (-y or --yes isn’t required).

$ heroku keys:add ~/.ssh/id_ed25519.pub
Uploading /Users/adam/.ssh/id_ed25519.pub SSH key... done

Heroku sends an email notification to the user’s email address after uploading a new key for security purposes.

Remove Keys From a Heroku Account

Keys that must be revoked and disassociated with a Heroku account are removable via the Heroku CLI and Heroku Dashboard.

Revoke a key using the Heroku CLI using keys:remove:

$ heroku keys:remove adam@workstation.local
Removing adam@workstation.local SSH key... done

If the key doesn’t have a name or doesn’t have a unique name, specify a portion of the public key string when removing the key via the CLI. For example:

$ heroku keys:remove AAAAAAAAAA
Removing adam@workstation.local SSH key... done

Remove all keys on a user account with keys:clear:

$ heroku keys:clear
Removing all SSH keys... done

Revoke a key using the Heroku Dashboard on the Account Settings page, under the SSH Keys section. Click the X to delete a key.

View Associated Keys

View a list of all of the keys associated with your account using the keys command:

$ heroku keys
=== user@example.com Keys
ssh-ed25519 AAAABDD3cC...2kPRNJqfKp user@example.com

Append --long to keys to see the entire output of the key string. If the user account has multiple keys, consider redirecting the command’s output to text (heroku keys --long > keys.txt) or piping the output to less (heroku keys --long | less) for added readability.

Validate Key Functionality

Confirm assigned SSH key(s) work by starting a one-off dyno for an app within a Shield Private Space:

$ heroku run bash -a shield-space-app-name

A successful connection indicates the key(s) are correct and functioning properly.

Common SSH Key Problems

Configured Key Mismatch

A common source of authentication failure when using an SSH key provided to Heroku is that the uploaded key doesn’t match the key provided during the authentication process. If, during testing, Permission denied (publickey) is displayed, validate the key’s functionality and confirm which key ssh is using. ssh -v prints the absolute path for the key with this message:

debug1: Offering public key: /path/to/key_file ...

If the key doesn’t match, either upload the correct key to Heroku or configure ssh to use a different key for the heroku.com host. Place the following in .ssh/config:

Host heroku.com
  HostName heroku.com
  IdentityFile /path/to/key_file
  IdentitiesOnly yes

Replace /path/to/key_file with the absolute path to the appropriate key without the .pub extension.

Key Already in Use

If This key is already in use by another account appears when attempting to upload an SSH key, the key is associated with another Heroku user. Confirm Heroku has the correct key, log into the other account and remove the SSH key, or generate a new key and upload it.