Set up Pipelines SSH keys on Windows

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 Windows

Download and install Git for Windows

  1. Download and run the installer from https://gitforwindows.org/. The options at each step should be suitable. When you reach the step about choosing the SSH executable, ensure the bundled OpenSSH is selected.

  2. Once the installation is complete, open Git Bash from the Start menu.

In the terminal, check that OpenSSH has been successfully installed by running the following command:

1 ssh -V

The output should show the installed version of OpenSSH.

Install Git for Windows with winget

To install OpenSSH as part of Git for Windows with the Windows package manager winget:

  1. Check that winget is installed. Open PowerShell and run:

    1 winget -v
  2. To install Git for Windows using winget install, run:

    1 winget install --id Git.Git -e --source winget
  3. Once the installation is complete, open Git Bash from the Start menu.

In the terminal, check that OpenSSH has been successfully installed by running the following command:

1 ssh -V

The output should show the installed version of OpenSSH.

Install the Windows version of OpenSSH

This procedure assumes Git is already installed and accessible in PowerShell. If Git is installed and not accessible in PowerShell, you may need to add Git to the PATH environmental variable.

To install the Windows version of OpenSSH, follow the instructions in the Microsoft Docs Get Started with OpenSSH for Windows guide. Once OpenSSH is installed, you need to configure Git to use OpenSSH.

In PowerShell, check that OpenSSH has been successfully installed by running the following command:

1 ssh -V

The output should show the installed version of OpenSSH.

To find where ssh was installed, run Get-Command. For example:

1 2 3 4 5 > Get-Command ssh CommandType Name Version Source ----------- ---- ------- ------ Application ssh.exe 8.1.0.1 C:\Windows\System32\OpenSSH\ssh.exe

To configure Git to use the Windows version of OpenSSH, update the SSH command with git config, such as:

1 git config --global core.sshCommand C:/Windows/System32/OpenSSH/ssh.exe

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