Use SSH keys in Bitbucket Pipelines

You'll want to set up an SSH key in Bitbucket Pipelines if:

  • your build pipeline needs to authenticate with Bitbucket or other hosting services to fetch private dependencies.
  • your deployment pipeline needs to authenticate with a remote host or service before uploading artifacts.

Note that setting up an SSH key allows access to remote hosts for all users with write access to the Bitbucket repository. 

On this page

To set up remote host SSH authentication for Bitbucket Pipelines:

Step 1: Add an SSH key in Bitbucket

We recommend that you generate a new SSH key pair, but you can use an existing key pair if your key requirements differ from the Bitbucket 2048-bit RSA keys. Whichever way you add an SSH key, the private key is automatically added to the build pipeline (as an additional SSH key), and doesn't need to be specified in the bitbucket-pipelines.yml file.

If your Docker image already has an SSH key your build pipeline can use that key, and you don't need to add an SSH key in this step – go to Step 2!

Note that Bitbucket Pipelines supports one SSH key per repository. If you need to use more than one key, you can add them as secured Bitbucket Pipelines environment variables, and reference them in the bitbucket-pipelines.yml file. See the Use multiple SSH keys section below.

To generate a new SSH key pair (recommended):

  1. In the repository Settings, go to SSH keys under 'Pipelines'.
  2. Click Generate keys to create a new SSH key pair.

Now go to Step 2 below.

To add an existing key pair:

You can use an existing key pair if your key requirements differ from the Bitbucket 2048-bit RSA keys.

For security reasons, you should never add your own personal SSH key – you should use an existing bot key instead.

  Click here for details on how to add an existing key...
  1. In the repository Settings, go to SSH keys
  2. Paste the private and public keys into the provided fields, then click Save key pair:

Step 2: Update the known hosts

The host fingerprint allows you to visually verify that the public key presented by a remote host actually matches the identity of that host, helping to avoid spoofing and man-in-the-middle attacks. Storing the fingerprint in Bitbucket locally along with the host address means that future communications with that host can be automatically verified.

In the repository Settings, go to SSH keys, and add the address for the known host. Click Fetch to see the host's fingerprint:

Note that Bitbucket Pipelines automatically adds the fingerprint for the Bitbucket and GitHub sites to all pipelines (but doesn't display that in the UI shown above).


Step 3: Add the public key to a remote host

You must install the public key on the remote host before Pipelines can authenticate with that host. 

Bitbucket Cloud repositories

If you want to access some other Bitbucket Cloud repository as part of your Pipelines builds, you can add the public key directly to the Bitbucket repo (see Use access keys in Bitbucket), perhaps after having generated the key in Pipelines as described in Step 1 above.

All other 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:

$ ssh-copy-id -i

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 Bitbucket Pipelines environment variables, and referencing them in the bitbucket-pipelines.yml file.

  Click to read how to use multiple SSH keys...

Step 1: Generate an SSH key (if necessary) 

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

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


Step 2: Encode the private key

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

$ base64 < my_ssh_key


Step 3: Add the key as a secure environment variable

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

  • Environment 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 environment variable, but instead generate a new SSH key-pair for Pipelines that easily be disabled if it is compromised.

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, choose Settings, then Environment 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.

    See Environment variables in Bitbucket Pipelines for more information. 


Step 4: Install the public key on a remote host

Add the public key to the remote host as described above.


Step 5: Create the my_known_hosts file and add it to your repo

The known_hosts file contains 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 following command:

    $ 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 that has previously accessed the remote host via SSH. You can remove all unrelated lines.


Step 6: 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 configure SSH for Docker containers that run your pipelines:

image: node:6    # specify your Docker image here
    - step:
           - 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 `hostname` as $USER"'
The example above just connects to a server and echoes "connected to <server> as <user>". You can modify the last line to use  scp to transfer files or  git to clone files from a remote server via SSH.

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport