Use multiple SSH keys in your pipeline

Bitbucket Pipelines supports one SSH key per repository. However, you can use multiple keys with a pipeline by adding them as secured variables, and referencing them in the bitbucket-pipelines.yml file. Follow the steps below to set up and use multiple SSH keys in your pipeline.

Generate an SSH key (if necessary) 

Generate an key pair without a passphrase. On Linux or OS X, you can run the following in a terminal:

1 ssh-keygen -t rsa -b 4096 -N '' -f my_ssh_key

Encode the private key

Pipelines does not currently support line breaks in environment variables, so base-64 encode the private key by running:


1 base64 -w 0 < my_ssh_key

Mac OS X

1 base64 < my_ssh_key


1 [convert]::ToBase64String((Get-Content -path "~/.ssh/my_ssh_key" -Encoding byte))

Add the key as a secure variable

There are security risks associated with passing private SSH keys as repository variables:

  • Repository variables get copied to child processes that your pipelines build may spawn.

  • Secured variables can be retrieved by all users with write access to a repository.

We recommend that you never pass your own personal SSH key as an repository variable, but instead generate a new SSH key-pair for Pipelines that easily be disabled if it is compromised. It may also be worth using deployment variables, which you can combine with deployment permissions to control access.

Copy the encoded key from the terminal and add it as a secured Bitbucket Pipelines environment variable for the repository:

  1. In the Bitbucket repository, select Repository settings, then under Pipelines, select Repository variables.

  2. Copy the base64-encoded private key from the terminal.

  3. Paste the encoded key as the value for an environment variable. Make sure to check Secured.

Secured highlighted with box checked

Install the public key on a remote host

You must install the public key on the remote host before Pipelines can authenticate with that host. If you want your Pipelines builds to be able to access other Bitbucket repos, you need to add the public key to that repo.

Remote hosts

If you have SSH access to the server, you can use the ssh-copy-id  command. Typically, the command appends the key to the ~/.ssh/authorized_keys file on the remote host:

1 ssh-copy-id -i my_ssh_key username@remote_host

Test the SSH access to the server:

1 ssh -i ~/.ssh/my_ssh_key user@host

If you are creating, rather than modifying the .ssh files you may need to change their permissions

  • chmod 700 ~/.ssh

  • chmod 600 ~/.ssh/authorized_keys

Other Bitbucket Cloud repositories

If you want your Pipelines builds to be able to access a different Bitbucket repository (other than the repo where the builds run):

  1. Add an SSH key to the settings for the repo where the build will run, as described in Step 1 above (you can create a new key in Bitbucket Pipelines or use an existing key).

  2. Add the public key from that SSH key pair directly to settings for the other Bitbucket repo (i.e. the repo that your builds need to have access to). 
    See Access keys for details on how to add a public key to a Bitbucket repo.

Create the my_known_hosts file and add it to your repo

The known_hosts file contains the DSA host keys of SSH servers accessed by the user. It's important to verify that you're connecting to the correct remote host. Note that Bitbucket Pipelines automatically adds the fingerprint for the Bitbucket and GitHub sites to all pipelines.

  1. Create the my_known_hosts file that includes the public SSH key of the remote host. You can do this by executing the ssh-keyscan command:

    1 $ ssh-keyscan -t rsa > my_known_hosts
  2. Commit the my_known_hosts file to your repository from where your pipeline can access it.

Alternatively, you can copy an existing known_hosts file from the ~/.ssh directory of a user who has previously accessed the remote host via SSH. You can remove all unrelated lines.

Tie everything together in the bitbucket-pipelines.yml file

Pipelines spins up a new Docker container environment for every build. You can use the SSH key by referencing it in the bitbucket-pipelines.yml file. 

To reference the SSH key for Docker containers that run your pipelines:

1 2 3 4 5 6 7 8 9 image: node:6 # specify your Docker image here pipelines: default: - step: script: - mkdir -p ~/.ssh - cat my_known_hosts >> ~/.ssh/known_hosts - (umask 077 ; echo $MY_SSH_KEY | base64 --decode > ~/.ssh/id_rsa) - ssh <user>@<host> 'echo "connected to `host` as $USER"'

The example above just connects to the host and echoes "connected to 'host' as <user>".

Note that the ssh command in the final line will use your default SSH identity. To specify a different key, use the -i option like this:

1 ssh -i ~/.ssh/my_other_ssh_key <user>@<host>

You can also modify the last line to use scp to transfer files or git to clone files from a remote server via SSH.

Additional Help