Complete Guide to Generate SSH Key, Add to Bitbucket & Fetch a Project
Add SSH key to Bitbucket – if you are working with Git and remote repositories, using SSH is the most secure and professional way to connect your system to a remote server. Instead of entering your username and password every time, SSH allows you to authenticate using cryptographic keys — making your workflow faster, safer, and more reliable.
This guide will help you understand both the concept and the practical implementation of SSH in a simple, step-by-step manner.
You will learn:
• What SSH is
• How to generate an SSH key
• How to add it to Bitbucket
• How to clone a project
• How to fetch the latest updates
• How to test the SSH connection
Let’s begin step by step.
What is SSH?
SSH (Secure Shell) is a secure communication protocol that allows you to connect to remote systems over an encrypted network.
It ensures:
- Data is encrypted during transmission.
- Authentication is secure
- Remote access is protected
In Git workflows, SSH verifies your identity when you push or pull code from repositories.
What is an SSH Key?
SSH authentication works using a key pair system:
• Public Key – Shared with Bitbucket/server
• Private Key – Stored securely on your computer
When you try to connect, the server checks if your private key matches the stored public key. If they match, the system grants access automatically.
Why SSH keys are better than passwords:
- Strong encryption
- No need to enter credentials repeatedly
- Less risk of brute-force attacks
Generate an SSH Key
Generating an SSH key creates a secure identity for your machine.
This creates a strong 4096-bit RSA key and labels it with your email for identification.
By saving it in the default ~/.ssh/ folder:
- Git automatically detects it
- You usually don’t need any additional configuration.
After generation:
id_rsa -> Private key (keep this secure and never share)id_rsa.pub -> Public key (share with Butbucket)Step 1: Open Terminal
Before generating an SSH key, you need to open a command-line interface (Terminal).
The Terminal lets you run system commands like ssh-keygen, which you need to create your SSH key.
Windows
(This opens Command Prompt where you can run SSH commands.)
Press Windows + R → Type cmd → Press Enter
MacOS
(This opens the macOS Terminal application to execute SSH commands.)
Press ⌘ + Space → Type Terminal → Press Enter
Step 2: Generate SSH Key
In this step, you will generate a new SSH key pair for your system.
This key pair will be used to securely authenticate your machine with remote repositories like Bitbucket.
Recommended (Modern & Secure Option)
Run this command:
ssh-keygen -t ed25519 -C "your_email@example.com" Replace your_email@example.com with your actual email.
Why Ed25519 ?
Ed25519 is the modern industry standard for SSH keys. It provides:
- Strong security
- Faster performance
- Smaller key size
👉 It is recommended for all new SSH keys.
Alternative (RSA – Older but Still Supported)
If you need compatibility with older systems, you can use RSA:
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"This creates a strong 4096-bit RSA key and tags it with your email.
What it means:
• -t ed25519 → Uses the modern Ed25519 algorithm (recommended)
• -t rsa → Uses RSA algorithm (legacy compatibility)
• -b 4096 → Sets RSA key strength to 4096 bits
• -C → Adds a label (usually your email) to identify the key
Press Enter to execute the command.
Step 3: Save Location
After running the ssh-keygen command, the system will ask where you want to save the SSH key file.
This determines the folder where your private and public keys will be stored.
You’ll see:
Enter file in which to save the key:
Just press Enter
(It saves to the default location: ~/.ssh/)
The default location is recommended because SSH automatically looks for keys inside the .ssh folder in your home directory.
If an SSH key is already saved in that location, it will ask:
Overwrite (y/n)?
Just press y → then press Enter
(This replaces the old SSH key with the new one.)
Step 4: Passphrase (Optional)
After choosing the save location, the system will ask you to set up a passphrase.
A passphrase adds an extra layer of security to your SSH key. Even if someone gets your private key file, they cannot use it without the passphrase.
It will ask:
“Enter passphrase:”
You can:
• Enter a password (recommended)
Adds extra security. You will need to enter it when using the SSH key.
• Or press Enter 2 times to skip
No passphrase will be set. Easier, but slightly less secure.
Done!
Your SSH key pair has now been successfully generated.
Two files are created inside the ~/.ssh/ folder. These files work together for secure authentication.
File 1: id_rsa
Purpose: Private Key (keep secret never share this file with anyone
File 2: id_rsa.pub
Purpose: Public Key (this is the key you add to Bitbucket or other Git platforms.
Important:
- The private key (id_rsa) stays on your computer.
- The public key (id_rsa.pub) is safe to share with services like Bitbucket.
- Never upload or send your private key to anyone.
Step 5: Copy Public Key
Now you need to copy your public key (.pub file) and add it to Bitbucket (or any Git platform).
️Important:
Only copy the public key — never share your private key.
On macOS – Copy Directly
Run this command:
pbcopy < ~/.ssh/id_rsa.pubThis copies the key directly to your clipboard. Now you need to copy your public key (.pub file) and add it to Bitbucket (or any Git platform).
Only copy the public key, never the private key.
Now just paste (⌘ + V) wherever needed (like Bitbucket).
On macOS – Copy Manually
If you prefer manual method:
Press command + Shift + G → Type / ~/.ssh → Enter
Then:
• Open the file ending with .pub (example: id_rsa.pub)
• Copy the entire key
Your key will look something like this:
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQ...Make sure you copy the entire line.
On Windows
You can open the public key file directly:
type “C:\UsersProfileName\.ssh\id_ed25519.pub” (Replace YourProfileName with your actual Windows username.)
OR copy directly using Command Prompt:
clip < C:\useProfileName\.ssh\id_ed25519.pubThis copies the key directly to your clipboard.
Now just paste (⌘ + V) wherever needed (like Bitbucket).
Step 6: Add SSH Key to Bitbucket
- Go to https://bitbucket.org
- Log in to your account
- Go to Settings
- Click on Personal Bitbucket settings
- On left side Click on Security
- Click SSH keys
- Click Add key
- Paste your SSH Public key
- Click Add key
Your system is now authorized.
Clone the Project Using SSH
Open your repository in Bitbucket.
- Click Clone
- Select SSH
- Copy the SSH URL
It will look like:
git@bitbucket.org:username/projectname.gitNow open Terminal or Command Prompt.
Navigate to your desired folder:
cd Desktop
Clone the project:
git@bitbucket.org:username/projectname.gitYour project will be downloaded successfully.
The project download may take some time: –
Step 7: Fetch or Pull Latest Updates
After setting up SSH and cloning the repository, you should regularly update your local project with the latest changes from the remote repository (like Bitbucket).
If the project is already cloned:
Go into the project folder:
cd projectname(Replace projectname with your actual project folder name.)
To fetch updates:
git fetch• Downloads the latest changes from the remote repository
• Does not automatically merge them into your current branch
• Safe way to check what others have pushed
To pull latest changes:
git pull• Fetches the changes
• Automatically merges them into your current branch
• Keeps your local project up to date
Tip:
Use git fetch if you just want to see updates.
Use git pull if you want to directly update your local code.
Step 8: Test SSH Connection
After adding your public key to Bitbucket, you should verify that your SSH connection is working correctly.
You can test your SSH connection using:
ssh-T git@bitbucket.orgWhat this does:
• ssh → Starts a secure shell connection
• -T → Disables terminal access (used only for authentication test)
• git@bitbucket.org → Connects to Bitbucket via SSH
If Successful
You will see a message like:
authenticated via ssh key.
This means:
✔ Your SSH key is correctly added
✔ Your system is successfully connected to Bitbucket
✔ You can now push and pull without username/password
If Not Working
You may see:
Permission denied (public key).
This means:
• SSH key is not added to Bitbucket
• Or wrong key is being used
• Or SSH agent is not running
Common Error: Permission Denied (public key)
1. Permission Denied (public key)
Error:
If you see:
Permission denied (publickey)Why This Happens:
- This error usually occurs when:
- Your SSH key is not added to Bitbucket
- You are using HTTPS instead of SSH
- Your SSH key is not stored in the correct directory (~/.ssh)
How to Fix:
- Ensure you’ve added your public key to your Bitbucket account
- Verify you are using the SSH URL (not HTTPS)
- Check that your key exists in ~/.ssh/
2. Host Key Verification Failed
Error:
If you see:
Host key verification failed
Why This Happens:
Your system does not recognize the remote host, or the host key may have changed.
How to Fix:
To resolve this, run the following command to add Bitbucket to your known hosts:
ssh-keyscan bitbucket.org >> ~/.ssh/known_hosts 3. SSH Agent Not Running
Issue:
Your SSH key is not being used because the SSH agent is not running.
Why This Happens:
The SSH agent is responsible for managing your private keys. If it’s not active, authentication fails.
How to Fix:
Start the SSH agent:
eval "$(ssh-agent -s)"Then add your key:
ssh-ad~/.ssh/id_ed255194. Bad Permissions on Private Key
Error:
If you see:
Permissions are too open
Why This Happens:
SSH requires strict permission on private keys. If permissions are too open, SSH will reject the key.
How to Fix:
Set the correct permissions:
chmod 600 ~/.ssh/id_ed25519Still Facing Issues?
If the problem continues, refer to the official Bitbucket SSH troubleshooting guide:
👉 https://support.atlassian.com/bitbucket-cloud/docs/troubleshoot-ssh-issues/
Final Thoughts
Most SSH issues come down to a few common misconfigurations—wrong keys, incorrect permissions, or missing setup steps. By carefully following the fixes above, you can resolve most problems quickly and get back to working with your repositories smoothly.
Conclusion
You have now successfully completed the essential steps to work with Git using SSH. First, you generated the SSH key. Then, you securely added it to Bitbucket and configured it for access. After that, you cloned the repository using SSH instead of HTTPS. Next, you fetched and pulled updates efficiently. Finally, you tested the SSH connection to ensure everything works correctly.
As a result, the workflow becomes more secure through encrypted authentication. At the same time, daily operations run faster by eliminating repeated credential prompts. Moreover, this approach reflects a professional, industry-standard method of working with version control systems.
Overall, developers now use Git with best practices to support scalability, enhance security, and improve efficiency in real-world development environments.
Now, you have successfully completed the essential steps to work with Git using SSH. First, you generated an SSH key. Then, you securely added it to Bitbucket and configured it for access. After that, you cloned your repository using SSH instead of HTTPS. Next, you fetch and pull updates efficiently. Finally, you tested your SSH connection to ensure everything is working correctly.
As a result, you now work with a more secure workflow through encrypted authentication. At the same time, your daily operations are faster because you no longer need to enter credentials repeatedly. Moreover, this approach follows a professional, industry-standard method for working with version control systems.
Overall, you are now using Git with best practices that support scalability, security, and efficiency in real-world development environments.
Click here to read more blogs like this.
I am a Junior SDET specializing in mobile application testing across Android and iOS platforms. I have hands-on experience in test automation, functional testing, and identifying defects to improve app quality. I work closely with development teams to ensure smooth releases and reliable performance. I am passionate about building efficient testing solutions and continuously enhancing my technical skills.