Step-by-Step Guide: Create an SSH Key, Add it to Bitbucket, and Clone a Repository Using SSH
This guide assumes you are using:
Windows
Visual Studio Code
Git for Windows (Git Bash)
Bitbucket Cloud
Step 1: Install Git
If you haven't installed Git yet:
Download Git from:
https://git-scm.com/downloads
Install it using the default settings.
Verify installation.
Open Visual Studio Code.
Open the terminal:
Terminal → New Terminal
Click the dropdown next to the + button and choose:
Git Bash
Run:
git --version
Example:
git version 2.49.0.windows.1
If you see a version number, Git is installed correctly.
Step 2: Check if you already have SSH keys
Run:
ls -al ~/.ssh
You might see something like:
id_rsa
id_rsa.pub
known_hosts
or
id_ed25519
id_ed25519.pub
If you already have an SSH key that you want to reuse, you can skip to Step 6.
Otherwise continue.
Step 3: Generate a new SSH key
Modern Git recommends using Ed25519.
Run:
ssh-keygen -t ed25519 -C "your-email@example.com"
Example:
ssh-keygen -t ed25519 -C "john@gmail.com"
You'll see:
Generating public/private ed25519 key pair.
Enter file in which to save the key:
Simply press:
Enter
to accept the default:
C:\Users\YourName\.ssh\id_ed25519
It then asks:
Enter passphrase (empty for no passphrase):
Just press Enter.
Then confirm it.
You'll see something like:
Your identification has been saved in:
id_ed25519
Your public key has been saved in:
id_ed25519.pub
Step 4: Verify the key was created
Run:
ls ~/.ssh
You should see
id_ed25519
id_ed25519.pub
The files mean:
FilePurpose
id_ed25519
Private key (keep secret)
id_ed25519.pub
Public key (share with Bitbucket)
Never share the private key (id_ed25519).
Step 5: Start the SSH Agent
Run:
eval "$(ssh-agent -s)"
Example output:
Agent pid 2345
Step 6: Add your private key to the SSH Agent
Run:
ssh-add ~/.ssh/id_ed25519
Example:
Identity added:
Verify it:
ssh-add -l
Example:
256 SHA256:xxxxxxxxxxxxxxxx
Step 7: Copy your public key
Display the key:
cat ~/.ssh/id_ed25519.pub
You'll see something like:
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGkM...
Copy the entire line, including:
ssh-ed25519
through to your email address at the end.
Step 8: Log in to Bitbucket
Go to:
Sign in.
Step 9: Open SSH Keys settings
Click your avatar (top-right).
Choose:
Personal settings
Then:
Security
Then:
SSH Keys
Click:
Add Key
Step 10: Add the SSH Key
Give it a label, for example:
My Laptop
Paste the public key into the Key box.
Click:
Add SSH Key
Done!
Step 11: Test the connection
Back in Git Bash:
Run:
ssh -T git@bitbucket.org
The first time you'll see:
The authenticity of host 'bitbucket.org' can't be established.
Type:
yes
Press Enter.
You should then see something similar to:
authenticated via ssh key.
You can use git to connect to Bitbucket.
If you see an authentication success message, your SSH key is configured correctly.
Step 12: Find the SSH Clone URL
Open your repository in Bitbucket.
Click:
Clone
Select:
SSH
You'll see something like:
git@bitbucket.org:company/project.git
Copy it.
Step 13: Clone the Repository
In Git Bash:
Navigate to where you want the project:
cd ~/Documents/Projects
Clone:
git clone git@bitbucket.org:company/project.git
Example:
git clone git@bitbucket.org:mycompany/react-app.git
Output:
Cloning into 'react-app'...
Receiving objects...
Resolving deltas...
Done!
Step 14: Open the Project in VS Code
Navigate into the repository:
cd react-app
Open it in Visual Studio Code:
code .
The project will open in a new VS Code window.
Step 15: Verify the Remote Uses SSH
Run:
git remote -v
You should see something like:
origin git@bitbucket.org:company/project.git (fetch)
origin git@bitbucket.org:company/project.git (push)
If you see an https:// URL instead, the repository is using HTTPS rather than SSH.
Step 16: Test Push Access
Create a test file:
echo "Hello" > test.txt
Commit it:
git add .
git commit -m "Test SSH authentication"
Push:
git push
If the push succeeds without asking for your Bitbucket username and password, SSH authentication is working correctly.
Common Errors and Fixes
ErrorCauseSolution
Permission denied (publickey)
SSH key not added to Bitbucket or SSH agent
Re-run ssh-add ~/.ssh/id_ed25519 and verify the public key is added in Bitbucket
Repository not found
Incorrect repository URL or insufficient permissions
Verify the SSH URL and ensure your Bitbucket account has access
Host key verification failed
Outdated or incorrect known_hosts entry
Remove the old Bitbucket entry from ~/.ssh/known_hosts and reconnect
Could not open a connection to your authentication agent
SSH agent is not running
Start it with eval "$(ssh-agent -s)" before running ssh-add
code: command not found
VS Code command-line tool isn't installed
In VS Code, press Ctrl+Shift+P, run Shell Command: Install 'code' command in PATH (or reinstall VS Code with the PATH option enabled on Windows)
Following these steps gives you a secure SSH setup for Bitbucket, allowing you to clone, pull, and push repositories without entering your credentials each time.