How to Add an SSH Key to Bitbucket Step by Step?

This article shows you, step by step, how to add an SSH key to Bitbucket from generating a key to testing the connection. By the end, you’ll connect fast and securely.

What Are SSH Keys?

SSH keys are a pair of cryptographic keys: a private key and a public key. Think of the public key as a padlock you hand out to services, and the private key as the only key that can open it. You store the private key safely on your machine; the public key gets pasted into Bitbucket. During connection, Bitbucket encrypts a challenge with your public key. Only your private key can decrypt it, proving your identity without ever exposing the secret itself. This process is far safer than a password that can be guessed, phished, or reused.

Why Use SSH Keys for Bitbucket?

Once set up, you never type a password again on that device for Git operations. Imagine a cross‑border e‑commerce seller who pushes product updates from several machines.

Without SSH keys, every script halts for credentials. With them, deployments flow automatically.

For system administrators juggling dozens of repos, SSH keys kill repeated login prompts. If you run CI/CD pipelines, an SSH key is essential because there’s no human available to enter a password. Bitbucket itself recommends SSH keys for their reliability and strong encryption.

How to Generate an SSH Key Pair Using PuTTYgen?

Download PuTTYgen from the official PuTTY site if you haven’t already.

Open PuTTYgen. Under Parameters at the bottom, select Ed25519 if it’s listed. If not, pick RSA and set the number of bits to 4096.

Click the Generate button and wiggle your mouse in the empty area to create randomness.

Once the key is ready, the uppermost text box shows the public key in OpenSSH format—exactly what Bitbucket needs. It starts with ssh-ed25519 or ssh-rsa. Make sure you copy the whole line, including the trailing comment like rsa-key-20240201. That comment doesn’t matter to Bitbucket, but the key string without it won’t work.

Click Save private key to store the .ppk file somewhere safe. If you’ll ever use this key with standard SSH clients, go to Conversions → Export OpenSSH key and save that as well. Now you have a complete key pair.

Also, you can generate the SSH Key Pair with ssh-keygen.

How to Add SSH Key to SSH Agent?

On most Linux desktops and macOS, the agent starts automatically. If it doesn’t, fire it up with:

eval "$(ssh-agent -s)"

Then load your key. For the default path:

ssh-add ~/.ssh/id_ed25519

Type your passphrase when asked.

On macOS you can store the passphrase in the Keychain by adding the --apple-use-keychain flag after ssh-add. For Git Bash on Windows, the same commands work after you start ssh-agent bash.

If you used PuTTYgen and have a .ppk file, launch Pageant (PuTTY’s agent), right‑click its tray icon, and choose Add Key.

Select your .ppk file. On Windows 10 or 11 with the built‑in OpenSSH client, open PowerShell as administrator, run Set-Service ssh-agent -StartupType Automatic and then Start-Service ssh-agent. After that, ssh-add ~\.ssh\id_ed25519 loads your key. Whatever path you take, the key is now cached and ready for Bitbucket.

How to Add Public Key to Bitbucket?

Now you just need to hand your public key to Bitbucket. Copy it to the clipboard first. On macOS:

pbcopy < ~/.ssh/id_ed25519.pub

On Linux you can use xclip -sel clip < ~/.ssh/id_ed25519.pub. If xclip isn’t installed, grab it with sudo apt install xclip (on Debian/Ubuntu) or simply run cat ~/.ssh/id_ed25519.pub and manually select and copy the output. On Windows PowerShell:

Get-Content ~\.ssh\id_ed25519.pub | Set-Clipboard

If you generated the key with PuTTYgen, you already copied the OpenSSH public key from the window.

Open your browser, log in to Bitbucket, and click your avatar in the bottom‑left corner. Select Personal settings, then look under Security in the left sidebar and click SSH keys. Hit the Add key button. Fill in the Label field with something memorable, like “Main Laptop.” Paste the entire public key into the Key field—no extra spaces or line breaks. Finally click Add key. Bitbucket may prompt you to confirm your account password. Once saved, Bitbucket recognizes your computer.

how to add ssh key to bitbucket FAQs

Q1: Do I need a separate SSH key for each Bitbucket account I use?
A: Yes, associate a unique public key with each account. You can reuse the same key pair on multiple machines, but it’s safer to generate distinct keys per device.

Q2: I’m getting a “no such identity” error when adding my PuTTYgen key via ssh-add. What’s wrong?
A: ssh-add only works with OpenSSH-format keys. In PuTTYgen, go to Conversions > Export OpenSSH key to save a compatible private key, then add that file with ssh-add.

Q3: Can I use the same SSH key for GitHub and Bitbucket?
A: Yes, you can add the same public key to both services. However, using separate keys isolates risks, so it’s a recommended security practice.

Conclusion

Adding an SSH key to Bitbucket is a quick, one‑off task that dramatically simplifies your daily Git workflow. It eliminates password prompts and strengthens security. Take five minutes to set this up, and you’ll enjoy a frictionless push‑and‑pull routine from then on. Now go ahead and give your fingertips a break.