SSH keys are the most secure and convenient way to connect Git to Bitbucket. Once set up, you clone, pull, and push without typing a password every time — and unlike an app password, a compromised laptop doesn't hand over a credential that works from anywhere. This guide walks through generating an SSH key, adding it to Bitbucket, testing the connection, and switching your repository over to SSH.
Everything here targets Bitbucket Cloud (bitbucket.org). The commands are the same on macOS, Linux, and Windows (via Git Bash or WSL).
Prerequisites
- Git installed and a terminal (Terminal on macOS/Linux, Git Bash or WSL on Windows)
- A Bitbucket account
- Two minutes
Step 1 — Check for an Existing SSH Key
Before generating a new key, check whether you already have one:
ls -al ~/.ssh
Look for a pair like id_ed25519 (private) and id_ed25519.pub (public), or the older id_rsa / id_rsa.pub. If you already have a key you're happy with, skip to Step 4. If not, generate one.
Step 2 — Generate a New SSH Key
Use the Ed25519 algorithm — it's faster and more secure than RSA, and it sidesteps a compatibility issue we'll cover in troubleshooting:
ssh-keygen -t ed25519 -C "your_email@example.com"
Press Enter to accept the default file location (~/.ssh/id_ed25519). When prompted for a passphrase, set one — it encrypts the private key on disk, so a stolen laptop doesn't equal a usable key. (If you're on an older system that doesn't support Ed25519, use ssh-keygen -t rsa -b 4096 -C "your_email@example.com" instead.)
One trap worth knowing: Atlassian's own setup docs show ssh-keygen -t ed25519 -b 4096, which reads like it produces a stronger key. It doesn't. Ed25519 has a fixed key size, so -b is silently ignored — generate a key that way and ssh-keygen -l -f ~/.ssh/id_ed25519.pub reports 256, not 4096. That's not a weakness (a 256-bit Ed25519 key is comparable in strength to RSA-3072), but if you were adding -b 4096 believing it did something, it doesn't. The flag only has meaning for RSA.
This creates two files:
id_ed25519— your private key. Never share it, never commit it, never leave it on a shared machine.id_ed25519.pub— your public key. This is the one you give to Bitbucket.
Step 3 — Add the Key to the ssh-agent
The ssh-agent holds your decrypted key in memory so you don't retype the passphrase on every Git operation. Start it and add your key:
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519
On macOS, store the passphrase in the Keychain so it persists across reboots:
ssh-add --apple-use-keychain ~/.ssh/id_ed25519
To avoid re-adding the key in every new shell, let SSH do it for you. Add this to ~/.ssh/config:
Host bitbucket.org
AddKeysToAgent yes
IdentityFile ~/.ssh/id_ed25519
AddKeysToAgent yes loads the key into the agent on first use instead of requiring an explicit ssh-add.
Step 4 — Copy Your Public Key
Print the public key and copy the whole line — it starts with ssh-ed25519 and ends with your email:
cat ~/.ssh/id_ed25519.pub
On macOS you can copy it straight to the clipboard with pbcopy < ~/.ssh/id_ed25519.pub; on Linux with xclip, and on Windows Git Bash with clip < ~/.ssh/id_ed25519.pub.
Step 5 — Add the Public Key to Bitbucket
- Log in to Bitbucket and open Personal settings (your avatar, bottom-left) → SSH keys.
- Click Add key.
- Give it a descriptive Label — the machine it lives on, e.g.
work-laptop, so you can revoke the right one later. - Paste the public key into the Key field.
- Click Add key.
That's it — the key is now tied to your Bitbucket account and works for every repository you have access to.
Step 6 — Test the Connection
Verify Bitbucket recognizes your key:
ssh -T git@bitbucket.org
The first time, you'll be asked to confirm Bitbucket's host fingerprint — type yes. On success, Bitbucket replies with a message ending in:
authenticated via ssh key.
You can use git to connect to Bitbucket. Shell access is disabled
Shell access is disabled
is expected and correct — Bitbucket only permits Git operations over SSH, not a login shell. Unlike GitHub, which greets you by username, Bitbucket's message confirms the authentication method; if you see it, the key worked.
Step 7 — Switch Your Repository to SSH
If you originally cloned over HTTPS, your remote still uses it. Point it at the SSH URL instead. Check the current remote:
git remote -v
If it shows https://your_username@bitbucket.org/..., update it to the SSH form:
git remote set-url origin git@bitbucket.org:workspace/repository.git
You'll find the exact SSH URL under Clone on the repository page (switch the dropdown from HTTPS to SSH). New clones can use it directly:
git clone git@bitbucket.org:workspace/repository.git
From here, git pull and git push authenticate with your key — no password prompts.
Personal Keys vs Repository Access Keys
The key you just added is a personal SSH key: it inherits your access to every repository, and it can read and write. That's right for your own machine, but wrong for a server or a CI job.
For automated systems, Bitbucket offers repository access keys (deploy keys) instead — a public key added to a single repository under Repository settings → Access keys, scoped to that one repo and read-only by default. The advantages:
- Scoped to one repository, not your whole account
- Read-only, so a compromised server can't push malicious commits
- Revocable independently of your personal credentials
Use a personal key on your laptop; use an access key on any server, build agent, or deployment tool. If you're pulling private packages during a build, the credential patterns in private repository dependencies show how to wire these up without leaking secrets into logs. And when you're setting up the server side, it's worth hardening the Linux server that stores any private key.
Two Bitbucket Accounts on One Machine
Work account and personal account on the same laptop is where most SSH setups fall over. The symptom is confusing: the wrong account's key gets offered, and Bitbucket rejects the push with a permission error even though both keys are valid.
The fix is a per-account Host alias in ~/.ssh/config:
# work account
Host bitbucket.org-work
HostName bitbucket.org
User git
IdentityFile ~/.ssh/id_ed25519_work
IdentitiesOnly yes
# personal account
Host bitbucket.org-personal
HostName bitbucket.org
User git
IdentityFile ~/.ssh/id_ed25519_personal
IdentitiesOnly yes
IdentitiesOnly yes is the load-bearing line. Without it, SSH offers every key it knows about in turn, and Bitbucket authenticates you as whichever one matches first — which may not be the account that owns the repository.
Then address the alias, not the real hostname, in your remote URL:
git clone git@bitbucket.org-work:workspace/repository.git
For a repository you already cloned:
git remote set-url origin git@bitbucket.org-work:workspace/repository.git
The alias only exists on your machine — Bitbucket never sees it. SSH rewrites it to bitbucket.org via the HostName line before connecting.
Using SSH Keys for Automated Deployments
The real payoff of an access key is hands-off deployment: a service reads from your Bitbucket repo over SSH and ships every push to your servers, with no passwords stored anywhere. This is the backbone of a Git-based deployment workflow and a reliable CI/CD pipeline.
DeployHQ follows exactly this model. When you connect a Bitbucket repository, DeployHQ generates a per-project public key for you to add as an access key — the step-by-step is in uploading your project's public key to Bitbucket manually. Once it's in place, every push can deploy automatically to your servers, with a full history and one-click rollback. Start a free DeployHQ trial and connect your Bitbucket repo in a couple of minutes.
Troubleshooting
Permission denied (publickey) — Bitbucket didn't accept your key. Confirm the key is added to the agent (ssh-add -l), that you pasted the .pub (public) key into Bitbucket, and that you copied the entire line with no missing characters.
git@bitbucket.org: Permission denied on push but pull works — you're using a read-only access key. Personal keys can push; repository access keys are read-only by design. Push with a personal key, or grant write access explicitly.
Too many authentication failures — SSH offers your keys one at a time and the server closes the connection after a fixed number of attempts (OpenSSH's MaxAuthTries, six by default). If your agent holds several keys, the right one may never get offered. Check what's loaded with ssh-add -l, and pin the key explicitly with IdentitiesOnly yes plus an IdentityFile line, as in the two-account config above.
Host key verification failed — the saved host fingerprint doesn't match. Remove the stale entry with ssh-keygen -R bitbucket.org and reconnect to re-accept the current fingerprint.
no mutual signature algorithm or key type ssh-rsa not in PubkeyAcceptedAlgorithms — a modern OpenSSH client refusing the legacy SHA-1 ssh-rsa signature. The clean fix is to switch to an Ed25519 key (Step 2); the full workaround for the ssh-rsa algorithm error covers RSA-with-SHA-2 if you must keep an RSA key. For other authentication failures, see our notes on SSH public key authentication errors.
Wrapping Up
Setting up SSH keys for Bitbucket takes a couple of minutes and pays off every day: passwordless Git, stronger security than app passwords, and the foundation for automated deployments. Generate an Ed25519 key, add the public half to Bitbucket, test with ssh -T, and switch your remotes to SSH. For servers and CI, reach for a read-only access key instead of your personal one.
Deploy your Bitbucket projects automatically — DeployHQ connects to Bitbucket over SSH and ships every push to your servers. See how easy automated deployment can be.
Questions about connecting Bitbucket to your deployments? Reach out at support@deployhq.com or on X (@deployhq).