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 1. Log in to Bitbucket and open **Personal settings** (your avatar, bottom-left) → **SSH keys**. 2. Click **Add key**. 3. Give it a descriptive **Label** — the machine it lives on, e.g. `work-laptop`, so you can revoke the right one later. 4. Paste the public key into the **Key** field. 5. 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](https://www.deployhq.com/blog/building-your-site-using-dependencies-from-a-private-repository) 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](https://www.deployhq.com/blog/secure-linux-server-for-deployments) 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](https://www.deployhq.com/blog/git-deployment-made-easy-with-deployhq) and a reliable [CI/CD pipeline](https://www.deployhq.com/blog/what-is-ci-cd). [DeployHQ](https://www.deployhq.com) follows exactly this model. When you connect a Bitbucket repository, [DeployHQ](https://www.deployhq.com) 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](https://www.deployhq.com/support/projects/updating-your-project-repository/uploading-your-public-key-to-bitbucket-manually). Once it's in place, every push can [deploy automatically to your servers](https://www.deployhq.com/blog/automate-website-deployments-from-git-without-downtime-with-deployhq), with a full history and one-click rollback. [Start a free](https://www.deployhq.com/signup)[DeployHQ](https://www.deployhq.com) 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](https://www.deployhq.com/support/common-server-errors/ssh-rsa-not-in-pubkeyacceptedalgorithms) 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](https://www.deployhq.com/support/common-server-errors/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](https://www.deployhq.com/pricing)** — [DeployHQ](https://www.deployhq.com) connects to Bitbucket over SSH and ships every push to your servers. See how easy [automated deployment](https://www.deployhq.com) can be. * * * Questions about connecting Bitbucket to your deployments? Reach out at [support@deployhq.com](mailto:support@deployhq.com) or on [X (@deployhq)](https://x.com/deployhq).