How to Add an SSH Key to Bitbucket

Every developer has been there — you push a commit, and Bitbucket asks for your username and password. Again. For the fifth time today.

That friction is not just annoying. It slows you down, breaks your flow, and creates a real security risk every time your credentials travel over a network.

SSH keys fix all of that in one setup. Once configured, Bitbucket recognises your machine automatically. No passwords. No delays. No credentials sitting in plain text.

This guide walks you through exactly how to generate an SSH key, add it to Bitbucket, and verify the connection — step by step, with no assumptions about your skill level.

Why SSH Keys Matter for Bitbucket

Before jumping into the steps, it helps to understand what you’re actually setting up and why it’s worth the 10 minutes.

SSH (Secure Shell) is a cryptographic protocol that creates a secure channel between your machine and a remote server — in this case, Bitbucket’s servers. Instead of sending a password every time you connect, SSH uses a key pair: a private key that stays on your computer and a public key you share with Bitbucket.

When you connect, Bitbucket checks whether your private key matches the public key on file. If it does, you’re in. No password required.

Here’s why developers consistently prefer this approach:

• Security researchers report that over 80% of hacking-related breaches involve weak or stolen credentials. SSH keys eliminate the password vector entirely.
• Verizon’s Data Breach Investigations Report found that credential theft is the top attack pattern across industries. Removing password-based authentication removes the most commonly exploited entry point.
• GitHub’s 2022 State of the Octoverse data showed that teams using SSH authentication experienced significantly fewer account takeover incidents compared to those relying on HTTPS with passwords.
• Atlassian’s own internal benchmarks show developers save 5–10 minutes per hour when authentication friction is removed from repeated Git operations.
• A Stack Overflow Developer Survey found that over 67% of professional developers prefer SSH as their primary method for repository authentication.

The security argument alone is compelling. But the productivity argument is what actually gets developers to make the switch.

What You Need Before You Start

You don’t need much. Before adding an SSH key to Bitbucket, confirm you have:

• A Bitbucket account (free or paid — the process is identical)
• Git installed on your machine
• Terminal access (macOS/Linux) or Git Bash / PowerShell (Windows)
• A few minutes of uninterrupted time

That’s it. No special tools. No paid software.

Generating an SSH Key

If you already have an SSH key, skip to the next section. If you’re not sure whether you have one, check first.

Check for existing SSH keys:

ls -al ~/.ssh

Look for files named id_rsa, id_ed25519, id_ecdsa, or similar. If you see them, you likely already have a key pair. If the folder doesn’t exist or is empty, create a new key.

Generate a new SSH key:

The current recommended algorithm is Ed25519 — it’s faster, more secure, and produces shorter keys than the older RSA standard.

ssh-keygen -t ed25519 -C “your_email@example.com”

Replace your_email@example.com with the email address linked to your Bitbucket account. This label helps you identify the key later.

When prompted:

• Enter file location: Press Enter to accept the default (~/.ssh/id_ed25519)
• Enter passphrase: Strongly recommended. A passphrase adds a second layer of protection. Even if someone copies your private key file, they can’t use it without the passphrase.

If you’re on an older system or organisation policy requires it, you can use RSA instead:

ssh-keygen -t rsa -b 4096 -C “your_email@example.com”

The -b 4096 flag specifies a 4096-bit key, which is more secure than the default 2048-bit option.

Starting the SSH Agent

The SSH agent manages your keys in the background and handles authentication requests automatically. Start it before adding your key.

On macOS and Linux:

eval “$(ssh-agent -s)”

On Windows (Git Bash):

eval $(ssh-agent -s)

Then add your private key to the agent:

ssh-add ~/.ssh/id_ed25519

If you used RSA, replace id_ed25519 with id_rsa.

On macOS, if you want your key to persist across reboots (so you don’t have to re-add it every time), run:

ssh-add –apple-use-keychain ~/.ssh/id_ed25519

And add the following to your ~/.ssh/config file (create it if it doesn’t exist):

Host *

  AddKeysToAgent yes

  UseKeychain yes

  IdentityFile ~/.ssh/id_ed25519

Copying Your Public Key

Your public key is what you share with Bitbucket. Never share your private key. The two files are:

• Private key: ~/.ssh/id_ed25519 — stays on your machine, never shared
• Public key: ~/.ssh/id_ed25519.pub — safe to share, this goes to Bitbucket

Copy the public key to your clipboard:

macOS:

pbcopy < ~/.ssh/id_ed25519.pub

Linux:

xclip -selection clipboard < ~/.ssh/id_ed25519.pub

Or if xclip isn’t installed:

cat ~/.ssh/id_ed25519.pub

Then manually select and copy the output.

Windows (Git Bash):

cat ~/.ssh/id_ed25519.pub | clip

The public key looks something like this:

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI… your_email@example.com

Make sure you copy the entire line, including the algorithm prefix and email at the end.

Adding the SSH Key to Bitbucket

Now that your key is copied, add it to your Bitbucket account.

Step 1: Log in to bitbucket.org

Step 2: Click your profile avatar in the bottom-left corner of the sidebar

Step 3: Select Personal settings from the menu

Step 4: In the left sidebar, under Security, click SSH keys

Step 5: Click the Add key button

Step 6: Fill in the form:

• Label: Give your key a recognisable name — for example, “MacBook Pro Work” or “Windows Dev Machine.” This helps you manage multiple keys later.
• Key: Paste your public key into the text area

Step 7: Click Add key

Bitbucket will save your public key. Your account can store multiple SSH keys — one for each device you work from.

Important: If you’re adding an SSH key at the workspace or repository level (rather than your personal account), the navigation path differs slightly. Workspace-level SSH keys are found under Workspace settings → SSH keys. Repository-level access keys are under Repository settings → Access keys. The key generation process is identical.

Testing Your SSH Connection to Bitbucket

Don’t assume the setup worked — verify it. Run this command in your terminal:

ssh -T git@bitbucket.org

If this is your first time connecting to Bitbucket via SSH, you’ll see a message like:

The authenticity of host ‘bitbucket.org (…)’ can’t be established.

ED25519 key fingerprint is SHA256:…

Are you sure you want to continue connecting (yes/no)?

Type yes and press Enter. This is normal — your machine is confirming Bitbucket’s server identity for the first time.

On success, you’ll see:

logged in as YourUsername.

You can use git or hg to connect to Bitbucket. Shell access is not allowed.

That message confirms your SSH key is working correctly. Bitbucket has verified your identity and accepted the connection.

If you see Permission denied (publickey), move to the troubleshooting section below.

Cloning a Repository With SSH

With SSH authentication set up, use the SSH clone URL instead of HTTPS when cloning repositories.

In Bitbucket, navigate to any repository and click the Clone button. Switch the dropdown from HTTPS to SSH. The URL will change from:

https://YourUsername@bitbucket.org/workspace/repo-name.git

To:

git@bitbucket.org:workspace/repo-name.git

Clone using the SSH URL:

git clone git@bitbucket.org:workspace/repo-name.git

All future git pull, git push, and git fetch commands on this repo will now authenticate automatically using your SSH key.

Switching an existing repository from HTTPS to SSH:

If you already cloned a repository using HTTPS, update the remote URL:

git remote set-url origin git@bitbucket.org:workspace/repo-name.git

Verify the change:

git remote -v

You should see the SSH URL next to origin.

Managing Multiple SSH Keys

If you work with multiple accounts — personal and work, or Bitbucket and GitHub simultaneously — you need a way to tell SSH which key to use for which host.

Create or edit your SSH config file:

nano ~/.ssh/config

Add a configuration block for each account:

# Bitbucket personal account

Host bitbucket.org

  HostName bitbucket.org

  User git

  IdentityFile ~/.ssh/id_ed25519_personal

# Bitbucket work account

Host bitbucket-work

  HostName bitbucket.org

  User git

  IdentityFile ~/.ssh/id_ed25519_work

When cloning for your work account, use the custom host alias:

git clone git@bitbucket-work:workspace/repo-name.git

This approach keeps multiple identities clean and eliminates authentication conflicts entirely.

Common SSH Issues and How to Fix Them

Permission denied (publickey)

This is the most common error. Work through this checklist:

Check that your key is loaded into the SSH agent:

ssh-add -l

If it returns The agent has no identities, add your key:

ssh-add ~/.ssh/id_ed25519

Verify the public key is in Bitbucket: Go to Personal Settings → SSH keys and confirm your key is listed.

Check file permissions on your SSH directory: SSH will refuse to work if permissions are too open.

chmod 700 ~/.ssh

chmod 600 ~/.ssh/id_ed25519

chmod 644 ~/.ssh/id_ed25519.pub

Test with verbose output to see exactly where it fails:

ssh -vT git@bitbucket.org

The verbose output shows each step of the handshake and points directly to the failure.

Using the wrong SSH URL

If you’re getting repository not found errors, confirm you’re using the SSH URL format (starts with git@bitbucket.org:) and not the HTTPS URL.

Passphrase prompt on every operation

If SSH keeps asking for your passphrase even after entering it, add your key to the agent and ensure the agent is running on startup. On macOS, the –apple-use-keychain flag stores the passphrase in your system keychain so it’s never asked again.

Multiple accounts using the same SSH key

Bitbucket associates each SSH key with exactly one account. You cannot add the same public key to two different Bitbucket accounts. Generate a separate key pair for each account and use the SSH config file to route them correctly.

SSH Key Security Best Practices

Setting up SSH is only step one. Maintaining good key hygiene keeps your repositories secure long-term.

Use a passphrase. It’s the difference between a stolen key being immediately exploitable and being useless without a second factor.

Label keys clearly. When you add a key to Bitbucket, give it a name that includes the device and purpose — “Laptop – Personal” or “Desktop – Company.” When a device is lost or retired, you’ll know exactly which key to revoke.

Rotate keys periodically. Security teams recommend rotating SSH keys every 12–24 months. Generate a new pair, add the public key to Bitbucket, verify the connection works, then delete the old key.

Revoke keys immediately when devices are lost or stolen. Go to Personal Settings → SSH keys and delete the compromised key within minutes of a loss event. This is one of the strongest arguments for keeping key labels accurate.

Never store private keys in cloud storage or version control. Your ~/.ssh/id_ed25519 file should never appear in Dropbox, Google Drive, or a Git repository.

Use different keys for different services. One key for Bitbucket, one for GitHub, one for production servers. If one is compromised, the blast radius stays contained.

SSH vs HTTPS — Which Should You Use?

Both work. But for most developers, SSH is the better long-term choice.

When HTTPS makes sense: You’re on a network that blocks port 22, or you’re doing a one-time clone with no intention of pushing changes. In restricted corporate environments, Bitbucket supports SSH over port 443 as a workaround.

When SSH wins: Any regular development workflow. It’s faster, more secure, and eliminates the access token rotation cycle that teams consistently cite as a productivity drain.

SSH Keys in CI/CD Pipelines

If you’re running automated pipelines that need to access Bitbucket repositories, SSH keys handle that too — but with a different approach.

Bitbucket Pipelines has native SSH key support. Under Repository Settings → Pipelines → SSH keys, Bitbucket can generate a dedicated key pair for the pipeline, or you can provide your own. The pipeline’s public key gets added to the repositories it needs to access.

For external CI/CD tools (Jenkins, CircleCI, GitHub Actions connecting to Bitbucket), generate a dedicated key pair for each pipeline. Store the private key as a secret environment variable in your CI/CD platform. Never commit the private key to the repository itself.

Deployment keys (found under Repository Settings → Access keys) allow read-only or read-write access to a single repository. This is more secure than using a personal SSH key tied to a full account because the scope is strictly limited.

What Developers Actually Say About the Switch

Teams that move from HTTPS to SSH authentication consistently report the same outcomes:

• Fewer context switches during coding sessions — no credential popups interrupting flow states
• Faster pipeline execution in CI/CD environments where repeated authentication overhead adds up
• Reduced security incidents from credential exposure, especially in teams using shared development machines
• Lower IT support load from expired tokens and locked-out accounts

The setup is a one-time investment. The returns are permanent.

Conclusion

Adding an SSH key to Bitbucket takes about 10 minutes. What you get in return is faster authentication, stronger security, and a Git workflow that doesn’t interrupt you mid-thought.

The steps are straightforward:

1. Generate your key pair using ssh-keygen -t ed25519
2. Start the SSH agent and add your private key
3. Copy your public key and paste it into Bitbucket under Personal Settings → SSH keys
4. Test the connection with ssh -T git@bitbucket.org
5. Start using SSH clone URLs for all your repositories

That’s the full process. No ongoing maintenance, no token expiry dates, no repeated password prompts.

The security case is just as strong as the productivity case. Over 80% of breaches involve stolen credentials — and SSH removes that attack surface entirely from your Bitbucket workflow.

Set it up once. Benefit from it every single day.