Set up Pipelines SSH keys on Linux

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

  • your build needs to authenticate with Bitbucket or other hosting services to fetch private dependencies.

  • your deployment needs to authenticate with a remote host or service before uploading artifacts.

  • you want builds to use tools such as SSH, SFTP or SCP.

An SSH public and private key pair must be added to the Bitbucket Cloud repository and the public key must be added to the remote service or machine.

When you set an SSH key on a Bitbucket repository, all users with write access to the repo will have access to the remote host. 

You should be able to push and pull to your Bitbucket Cloud repo with no problems. But, if you need to use SSH, for example, to use a bot account, or when branch permissions are enabled, see Set up an SSH key.

For SSH with Bitbucket repos see:

Not all available Docker images have SSH installed by default. If you are using the default pipelines image you'll be fine, but if you need to specify your own image, make sure SSH is either already installed, or install it with your script.

For example, depending on your image, including in your script:

apt-get update -y
apt-get install -y ssh

There are two options for creating SSH key pairs:

  • Automatically generate a key pair using the Bitbucket UI.

  • Manually generate and add a key pair.

Automatically generate a key pair using the Bitbucket UI

To automatically generate an SSH key pair using the Bitbucket UI:

  1. In Repository settings under Pipelines, select SSH keys.

  2. Select Generate keys to create a new SSH key pair.

To add the SSH key to another Bitbucket repository or a remote host, see Update the known hosts.

Manually generate and add a key pair

To manually generate and add an SSH key pair:

  1. Install OpenSSH on your device.

  2. Create an SSH key pair.

  3. Provide Bitbucket Cloud with the SSH key pair.

  4. Update the known hosts.

  5. Add the public key to a remote host or a Bitbucket repository.

Install OpenSSH on Linux

To install OpenSSH, we recommend using the OpenSSH package provided by your Linux distribution.

  • For Debian, Ubuntu, Linux Mint, and other Debian-based distributions:

    1 sudo apt update && sudo apt install openssh-client
  • For Fedora, CentOS, Red Hat Enterprise Linux, Oracle Linux, and other Fedora-based distributions:

    1 sudo dnf install openssh-clients
  • For Arch Linux and other Arch Linux-based distributions:

    1 sudo pacman -Sy openssh
  • For SUSE Linux, openSUSE Linux, and other SUSE-based distributions:

    1 sudo zypper install openssh

Create an SSH key pair

To create an SSH key pair:

  1. Open a terminal and navigate to your home or user directory using cd, for example:

    1 cd ~
  2. Generate a SSH key pair using ssh-keygen, such as:

    1 ssh-keygen -t ed25519 -b 4096 -C "{username@emaildomain.com}" -f {ssh-key-name}

    Where:

    • {username@emaildomain.com} is the email address associated with the Bitbucket Cloud account, such as your work email account.

    • {ssh-key-name} is the output filename for the keys. We recommend using a identifiable name such as bitbucket_work.

  3. When prompted to Enter passphrase, you can either provide a password or leave the password empty. If you input a password, you will be prompted for this password each time SSH is used, such as using Git command that contact Bitbucket Cloud (such as git push, git pull, and git fetch). Providing a password will prevent other users with access to the device from using your keys.

Once complete, ssh-keygen will output two files:

  • {ssh-key-name} — the private key.

  • {ssh-key-name}.pub — the public key.

Provide Bitbucket Cloud with the SSH key pair

To add an SSH key pair to a Bitbucket Pipeline:

  1. At bitbucket.org, navigate to the repository and select Repository settings.

  2. Under Pipelines, select SSH keys.

  3. Select Use my own keys.

  4. Open the private SSH key file (private keys don’t have a file extension) in a text editor. The public key should be in the .ssh/ directory of your user (or home) directory. The contents will be similar to:

    1 2 3 4 5 6 7 -----BEGIN OPENSSH PRIVATE KEY----- Uc9BJ5EXDPJnCMUcXlIFl2XeHysiRh3hurFnnpDvxL61PNNcVpLdvreFkKacfedsiRS39T KA8FC08Yqa8i22jfnAS38U0UHWLoNp2zinflG1AYbmj4dndRIO4d5qCMoWWnCfValxQ1T5 DNGsgnuK2aBBMoJC+tRRAd1WCKyU4h7WRd6chw9edEYrq3jIVKCEN4xLoPcM+o+e5vm5im i5NLmCx+UGboJy1AgK0j+Teme878fH0Eq1UoBbSb3JtAkr1tJ84SXO2wNQkRPCS4Tm4QQx FepYUKKEldljd2lOd2fUuTNKG9Ghall5MT59MtDrlWqsnk3bx442xqEqsbe2== -----END OPENSSH PRIVATE KEY-----
  5. Copy the contents of the private key file and paste the key into the Private key field.

  6. Open the public SSH key file (public keys have the .pub file extension) in a text editor. The public key should be in the .ssh/ directory of your user (or home) directory. The contents will be similar to:

    1 ssh-ed25529 LLoWYaPswHzVqQ7L7B07LzIJbntgmHqrE40t17nGXL71QX9IoFGKYoF5pJKUMvR+DZotTm user@example.com
  7. Copy the contents of the public key file and paste the key into the Public key field.

  8. Select Save key pair to save the SSH keys.

Update the known hosts

Pipelines provides a way for you to store, and inspect, the fingerprint of a remote host, along with the host address. This allows you to visually verify that the public key presented by a remote host actually matches the identity of that host, to help you detect spoofing and man-in-the-middle attacks. It also 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 the Fetch button to see the host's fingerprint. Note: 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).

Add the public key to a remote host or a Bitbucket repository

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.

Additional Help