Skip to main content
Last Reviewed: February 11, 2025

Generate and Add SSH Keys

Understand how to generate SSH keys to configure Git, SFTP, or Drupal Drush.


Interacting with remote Pantheon environments via Git, SFTP, WP-CLI, and Drush requires an SSH key for authentication. This is configured by adding your public SSH key to your user account on Pantheon. If you interact with your sites from multiple workstations (laptop, desktop, etc.), you must add a separate SSH key for each machine.

Info:
Note

Pantheon does not provide access to a shell environment over SSH. These directions allow you to authenticate operations on Pantheon like Git, SFTP, WP-CLI or Drush via SSH keys.

Pantheon supports ECDSA and RSA SSH keys. Currently, we do not support ed25519 keys.

Generate an SSH key

Use the steps in this section to generate your SSH key.

Watch: Generate a SSH Key and Add it to Your Dashboard

Create the key locally

The following steps are compatible with MacOS, Linux, and the Windows Subsystem for Linux (WSL). Windows users must install WSL before proceeding to the steps below.

  1. Open your terminal and enter the following command to generate a key:

    ssh-keygen -t rsa -m PEM

    Do not edit the default location of ~/.ssh/id_rsa unless you have a reason to change it. If the command says the key already exists, you can either overwrite it, or continue to the next step with your existing key.

  2. Set a passphrase for better security.

    We recommend using a passphrase, but it can conflict with some tools.

  3. Copy the contents of ~/.ssh/id_rsa.pub to your clipboard after the files are created.

    cat ~/.ssh/id_rsa.pub
  4. Run eval to start the SSH agent. The Agent pid output confirms that the agent started:

    eval `ssh-agent`
    Agent pid 86810
  5. Add the newly created key to the ssh-agent:

    ssh-add ~/.ssh/id_rsa

Add your SSH key to Pantheon

  1. Log in to your Pantheon Dashboard.

  2. Click your user icon in the top right then click Personal Settings, and go to the SSH Keys tab.

  3. If this is your first key, click Get Started, otherwise click Add New Key.

  4. Paste the copied public key into the box, and click Save.

    Adding SSH Keys

    Your computer is now set up to securely connect to the Pantheon Git server. You can view a list of available keys on the same page.

Test your new key (optional)

Try out your new key by interacting with your site using any one of the following methods:

Manage multiple keys (optional)

If you use multiple SSH keys to routinely authenticate your machine with other platforms or services other than Pantheon, you may benefit by configuring specific keys according to their specific usage.

For example, the following configuration tells your Pantheon sites to use your Pantheon key, while using a separate key for GitHub:

~/.ssh/config
Host github
    User git
    Hostname github.com
    PreferredAuthentications publickey
    IdentityFile ~/.ssh/github_rsa

Host codeserver.*.drush.in
    PreferredAuthentications publickey
    IdentityFile ~/.ssh/pantheon_rsa

Remove SSH Key from Pantheon

After removing SSH Keys from your user account, you will not be able to interact with remote Pantheon application and codeservers via Git, SFTP, Drush, or WP-CLI.

Removing SSH keys is separate from revoking the machine tokens used by Terminus to perform actions (e.g., creating Multidev environments) that can otherwise be done in the Pantheon Site Dashboard.

  1. Log in to your Pantheon Dashboard.

  2. Click your user icon in the top right then click Personal Settings, and go to the SSH Keys tab.

  3. Click the Revoke button next to the key you want to remove:

    Delete SSH Key

  4. Check the box in the confirmation prompt and click continue.

Troubleshooting

Authenticity & Fingerprint Prompts

Your first connection to any remote server over an SSH connection (like Git or SFTP) will prompt you to confirm the host identity:

The authenticity of host '[codeserver.dev.UUID.drush.in]:2222 ([IP.ADDRESS]:2222)' can't be established.
RSA key fingerprint is SHA256:yPEkh1Amd9WFBSP5syXD5rhUByTjaKBxQnlb5CahZZE.
Are you sure you want to continue connecting (yes/no)?

You can safely type yes and press enter to add the server's SSH key fingerprint to your computer's known_hosts file. Additional connections to this specific Pantheon container will complete successfully without prompts. However, you will be prompted to confirm connections following a container migration, which is part of regular maintenance on the platform. See the following Pro Tip to automatically accept all Pantheon connections.

Pro Tip: Trust All Pantheon Hosts

The key fingerprint is a representation of the public key, used by the remote server to identify itself. These public keys, along with private keys, form a keypair used by the Diffie-Hellman key exchange to encrypt communication between you and the server.

On a standard server system, the server administrator would publish their host keys and fingerprints publicly, so clients could match them to the keys presented at these prompts. On Pantheon however, application containers are created and destroyed too rapidly to maintain a public key list.

You can, however, easily tell your machine to automatically trust all Pantheon *.drush.in servers by disabling the StrictHostKeyChecking option in your SSH configuration file.

Warning:
Warning

Be aware that this disables a security feature and trusts your DNS system to always point you to the right IP addresses.

Open ~/.ssh/config (or create a new file if one does not exist) and add the following lines:

~/.ssh/config
Host *.drush.in
    StrictHostKeyChecking no

Now, requests to any *.drush.in server address should automatically accept the server's SSH key fingerprint without prompting you.

Control Path Error

You may receive the following error:

ControlPath too long fatal: Could not read from remote repository.

Check your SSH config files (by default, $HOME/.ssh/config and /etc/ssh/ssh_config) for a declaration like this:

ssh_config
Host *
ControlMaster auto
ControlPath ~/.ssh/control-%l.%r@%h:%p

There are two ways to fix this. First, try adjusting the Controlpath line as shown below:

ssh_config
Host *
ControlMaster auto
ControlPath ~/.ssh/control-%r

If this doesn't fix the issue, try creating an entry in your SSH configuration for your site specifically by its hostname. Don't use the ControlMaster option, instead use the ControlPath line as shown below, replacing SITE_UUID with your site's UUID:

ssh_config
Host *.SITE_UUID.drush.in
ControlPath ~/.ssh/control-%r

Server Refused to Allocate pty

This error occurs when a user is attempting to make a direct connection to Pantheon via SSH. Pantheon does not support direct SSH connections.

Authentication Prompts

Password requests may still occur after adding an SSH key to your Pantheon account if the corresponding key is not found by your local ssh-agent. Verify by listing the SSH fingerprints already loaded in your device's ssh-agent:

ssh-add -L | ssh-keygen -l -E md5 -f - | awk '{print substr($2,5)}'

The resulting string should match one of the keys listed in your Personal Settings.

To resolve, add your SSH key to the ssh-agent using the following command, replacing id_rsa with the name of your private key, if different:

ssh-add ~/.ssh/id_rsa

If you are using a Linux distribution such as Fedora 33 or later, make sure RSA keys are enabled in ~/.ssh/config:

Host *.drush.in
  PubkeyAcceptedKeyTypes=ssh-rsa
Info:
Note

Pantheon does not have access to keys that only exist on the host machine. You must ensure that your keys and, if applicable, your key agent are made available to the application running in the container, if you're using Lando, Docksal, or DDEV.

What if I can't install the Windows Subsystem for Linux?

Consider that Terminus, Pantheon's command-line interface, requires WSL for compatibility. This is why the process above expects WSL to be installed, however it is not a hard required for generating SSH keys.

If you are a Windows user and you are unable to install WSL on your machine, you may use the following process as an alternative:

Alternative steps to generate SSH keys on Windows
  1. Open your terminal and enter the following command to generate a key. This command works for Windows 10:

    ssh-keygen -t rsa -m PEM

    Do not edit the default location of ~/.ssh/id_rsa unless you have a reason to change it. If the command says the key already exists, you can either overwrite it, or continue to the next step with your existing key.

  2. Set a passphrase for better security.

    We recommend using a passphrase, but it can conflict with some tools.

  3. Copy the contents of ~/.ssh/id_rsa.pub to your clipboard after the files are created.

    type .ssh\id_rsa.pub
  4. Run start-ssh-agent to start the SSH agent. The output confirms the agent has started. Enter the passphrase, if it was previously set.

    start-ssh-agent
    Removing old ssh-agent sockets
    Starting ssh-agent:  done
    Enter passphrase for /c/Users/[user]/.ssh/id_rsa:
    Identity added: /c/Users/[user]/.ssh/id_rsa ([user@machine_name])