Set up personal SSH keys on Windows

The third-party Git Credential Manager (GCM) can be used as alternative method of connecting to Bitbucket Cloud from the Git CLI. If you do not want to configure SSH access for your Bitbucket Cloud account, you can the GCM, which is installed by default with Git for Windows, or you can download and install it from Git Credential Manager on GitHub. Note that the GCM works over HTTPS, not SSH. Ensure your Git remotes are using HTTPS, such as:
git clone https://{username}@bitbucket.org/{workspace}/{repository}.git

 

The Secure Shell protocol (SSH) is used to create secure connections between your device and Bitbucket Cloud. The connection is authenticated using public SSH keys, which are derived from a private SSH key (also known as a private/public key pair). The secure (encrypted) connection is used to securely transmit your source code between your local device and Bitbucket Cloud. To set up your device for connecting Bitbucket Cloud using SSH, you need to:

  1. Install OpenSSH on your device.

  2. Start the SSH service.

  3. Create an SSH key pair.

  4. Add your key to the SSH agent.

  5. Provide Bitbucket Cloud with your public key.

  6. Check that your SSH authentication works.

Install OpenSSH on Microsoft Windows

There are 3 methods for installing OpenSSH on Microsoft 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

Start the SSH agent

To allow git to use your SSH key, an SSH agent needs to be running on your device. The method for starting the SSH agent depends on how OpenSSH was installed.

Git for Windows users (including Winget-based Git installations)

From a git bash terminal, check if the SSH agent is running using the ps command. If the ssh-agent is already running, it should appear in the output, such as:

1 2 $ ps -a | grep ssh-agent tkelly 3291 0.0 0.0 6028 464 ? Ss 07:29 0:00 ssh-agent

To start the agent:

1 eval $(ssh-agent)

You may need to add this command to your ~/.bashrc to ensure the agent starts when you open a Git Bash terminal.

Windows OpenSSH users

From a PowerShell, check if the SSH Agent is running using the Get-Service command. For example:

1 2 3 4 5 > Get-Service ssh-agent Status Name DisplayName ------ ---- ----------- Stopped ssh-agent OpenSSH Authentication Agent

To start the agent:

1 > Start-Service ssh-agent

To configure the SSH agent to start each time the device is started, use the Set-Service command, such as:

1 > Set-Service -Name sshd -StartupType 'Automatic'

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.

These files will be stored in your user folder, such as C:\Users\<username>\<ssh-key-name>.

Add your key to the SSH agent

To add the SSH key to your SSH agent (ssh-agent):

  1. Run the following command, replacing the {ssh-key-name} with the name of the private key:

    1 ssh-add ~/{ssh-key-name}
  2. To ensure the correct SSH key is used when connecting to Bitbucket, update or create your SSH configuration file (~/.ssh/config) with the following settings:

    1 2 3 Host bitbucket.org AddKeysToAgent yes IdentityFile ~/.ssh/{ssh-key-name}

    Where {ssh-key-name} is the location of the private key file once it has been added to the ssh-agent.

Provide Bitbucket Cloud with your public key

To add an SSH key to your user account:

  1. At bitbucket.org, select your avatar (Your profile and settings) from the navigation bar at the top of the screen.

  2. Under Settings, select Personal settings.

  3. Under Security, select SSH keys.

  4. Select Add key.

  5. In the Add SSH key dialog, provide a Label to help you identify which key you are adding. For example, Work Laptop <Manufacturer> <Model>. A meaning full label will help you identify old or unwanted keys in the future.

  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 Key field of the Add SSH key dialog.

  8. Select Add key.

    • If the key is added successfully, the dialog will close and the key will be listed on the SSH keys page.

    • If you receive the error That SSH key is invalid, check that you copied the entire contents of the public key (.pub file).

Check that your SSH authentication works

To test that the SSH key was added successfully, open a terminal on your device and run the following command:

1 ssh -T git@bitbucket.org

If SSH can successfully connect with Bitbucket using your SSH keys, the command will produce output similar to:

1 2 3 authenticated via ssh key. You can use git to connect to Bitbucket. Shell access is disabled

 

 

Additional Help