Setting up SSH keys on Mac OS X for Bitbucket

March 20, 2014, 5:37 pm
Author: James Griffiths

If you're using a Git based source control management (SCM) service you'll need to create and configure SSH keys to facilitate trusted communication between your computer and the remote SCM repository. If you're using Mac OS X (or similar unix based system) then this process turns out to be relatively simple.

In the following article we'll show you how to accomplish this so you can safely and securely connect to one such SCM service - Bitbucket.

As with most server related tasks you'll need to fire up the Mac OS X Terminal to start the process of creating and configuring your SSH keys.

Confirm you're in your home directory (which you should be by default) by typing the following command: pwd which should show you something akin to the following:


If you find you're in a completely different location simply type cd ~ to get you back to your home directory.

Now begin the process of creating an SSH key using the following command:


By default this will create a 2048 bit length RSA private/public key pair which you will be prompted to provide a password for.

If you navigate into the .ssh folder in your home directory you should see the keys that have been generated, which will be named id_rsa and, by typing the command ls -al.

If you are planning to generate multiple keys for different applications it might be an idea to rename the keys that you generate to something unique such as the name of the project/service they relate to. If you were to do this renaming the keys might look something like the following:

mv id_rsa project_name_rsa

We now need to copy the public key (the one we wish to share with Bitbucket for communications between our local machine and the remote repository):

pbcopy < ~/.ssh/

You will need to paste the copied public key into your SSH keys section on your Bitbucket account so that your local machine can communicate with and exchange information with Bitbucket - see below.

Bitbucket repository enter SSH key form

Returning back to your Terminal type out the following to list your SSH keys: ls -a ~/.ssh.

If you don't see a list of keys being returned this probably means the shh-agent isn't running. To check if this is the case type out the following instruction:

ps -e | grep [s]sh-agent

If the SSH agent is running you should see something akin to the following output:

66129 ??         0:00.03 ssh-agent /bin/bash

If you don't see any output then force the ssh-agent to run with the following command:

ssh-agent /bin/bash

The ssh-agent stores the password for the private key that you created but firstly you have to add the identity of the private key to the ssh-agent in order for it to do this:

ssh-add ~/.ssh/id_rsa

You will be prompted for the passphrase that you used to generate the public/private key pair and, once this has been entered and confirmed, you should see the fingerprint of the key that has just been added to the ssh-agent with the following command:

ssh-add –l

Which should output something akin to the following:

The key fingerprint is:

If you see similar output then everything has been configured successfully and you can start exchanging information between your local machine and Bitbucket using the SSH protocol.


« Return to Posts

Post a comment

All comments are welcome and the rules are simple - be nice and do NOT engage in trolling, spamming, abusiveness or illegal behaviour. If you fail to observe these rules you will be permanently banned from being able to comment.