Set up Pipelines SSH keys on macOS

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:

• User-based SSH keys

• Repository Access keys

• Project Access keys

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

A version of OpenSSH should be pre-installed on macOS. To check if OpenSSH is installed, open a terminal and run:

The output should show the installed version of OpenSSH.

To use Homebrew to install a newer version of OpenSSH, run:

To check that OpenSSH was installed successfully, run:

The output should show the installed version of OpenSSH.

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. Generate a key pair without a passphrase.

Once complete, ssh-keygen will output two files:

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

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

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.

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 Repository settings, go to SSH keys under the Pipelines header, 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).

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:

Test the SSH access to the server:

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.