This guide walks you through configuring an SSH key for Bitbucket so you can authenticate securely without entering your username and password each time.
- Git installed (
git --version) - Bitbucket account
- Terminal access (macOS/Linux/Windows with Git Bash)
The SSH agent is a background process that manages your private keys for SSH authentication.
ps -ax | grep ssh-agent- If you see a line with
/usr/bin/ssh-agent, it’s already running. - If not, proceed to the next step to start it.
Start the agent if it’s not already running:
-
macOS / Linux:
eval "$(ssh-agent -s)"
-
Windows (Git Bash):
eval $(ssh-agent -s)
You should see something like:
Agent pid 59566
Create a new SSH key pair specifically for Bitbucket:
ssh-keygen -t rsa -b 4096 -C "your.email@example.com" -f ~/.ssh/bitbucket_work- This creates a 4096-bit RSA key.
- Press Enter when prompted to accept the default path.
- Optionally enter a passphrase for added security.
📁 This generates two files:
~/.ssh/bitbucket_work→ Private key~/.ssh/bitbucket_work.pub→ Public key
We now add the private key to the agent so it can be used automatically.
cat ~/.ssh/bitbucket_work | pbcopy🧠 This command loads your key into clipboard
If you get:
Could not open a connection to your authentication agent
Go back to Step 2 and ensure the agent is running.
- Copy your public key:
cat ~/.ssh/bitbucket_work.pub - Log in to Bitbucket
- Go to Personal Settings → SSH Keys
- Click Add Key
- Paste the key and give it a label (e.g.,
Work MacBook) - Save
Run the following to check if everything works:
ssh -T git@bitbucket.org🟢 If it’s working, you’ll see:
logged in as your-username
You can use git to connect to Bitbucket. Shell access is disabled.
🔴 If you see an error like:
Permission denied (publickey)Host key verification failed
Check:
- Your public key is added to Bitbucket
- The private key is loaded (
ssh-add -l) - You’re using the correct remote URL format
You can now clone repositories over SSH:
git clone git@bitbucket.org:your-team/your-repo.gitHappy coding!