Set up SSH for Git and Mercurial on Mac OSX/Linux

If you came to this page because you don't have SSH set up, then you have been using the secure hypertext transfer protocol (HTTPS) to communicate between your local system and Bitbucket. When you use HTTPS, you authenticate (supply a username and password) each time you take an action that requires a connection with Bitbucket. Who wants to do that? This page shows you how to use secure shell (SSH) to communicate with the Bitbucket server and avoid having to manually type a password all the time.

This page shows you how to set up and use a single default SSH identity on either OSX or Ubuntu Linux. If you want set up on Microsoft Windows , we have instructions for Set up SSH for Git -- deprecated and for Set up SSH for Mercurial -- deprecated

Finally, setting up an SSH identity can be prone to error. Allow yourself some time, perhaps as much as an hour depending on your experience, to complete this page. If you run into issues, check out Troubleshoot SSH Issues for extra information that may help you along.  You can even skip this whole page and continue to use HTTPS if you want.

Step 1. Read a quick overview of SSH concepts

To use SSH with Bitbucket, you create an SSH identity. An identity consists of a private and a public key which together are a key pair. The private key resides on your local computer and the public you upload to your Bitbucket account. Once you upload a public key to your account, you can use SSH to connect with repositories you own and repositories owned by others, provided those other owners give your account permissions. By setting up SSH between your local system and the Bitbucket server, your system uses the key pair to automate authentication; you won't need to enter your password each time you interact with your Bitbucket repository.

There are a few important concepts you need when working with SSH identities and Bitbucket.

  • You cannot reuse an identity's public key across accounts. If you have multiple Bitbucket accounts, you must create multiple identities and upload their corresponding public keys to each individual account. 
  • You can associate multiple identities with a Bitbucket account. You would create multiple identities for the same account if, for example, you access a repository from a work computer and a home computer. You might create multiple identities if you wanted to execute DVCS actions on a repository with a script – the script would use a public key with an empty passphrase, allowing it to run without human intervention.
  • RSA (R. Rivest, A. Shamir, L. Adleman are the originators) and digital signature algorithm (DSA) are key encryption algorithms. Bitbucket supports both types of algorithms. You should create identities using whichever encryption method is most comfortable and available to you.

Step 2. Ensure you have an SSH client installed

To use SSH, you need an SSH client on your local system. If you know you have a client installed, skip this section. Otherwise do the following:

  1. Open a terminal on your local system.
  2. Enter the following command to identify which version of SSH you have installed.
    If SSH is installed, you see something similar to the following:

    myhost:~ manthony$ ssh -v
    OpenSSH_5.6p1, OpenSSL 0.9.8r 8 Feb 2011
    usage: ssh [-1246AaCfgKkMNnqsTtVvXxYy] [-b bind_address] [-c cipher_spec]
               [-D [bind_address:]port] [-e escape_char] [-F configfile]
               [-I pkcs11] [-i identity_file]
               [-L [bind_address:]port:host:hostport]
               [-l login_name] [-m mac_spec] [-O ctl_cmd] [-o option] [-p port]
               [-R [bind_address:]port:host:hostport] [-S ctl_path]
               [-W host:port] [-w local_tun[:remote_tun]]
               [user@]hostname [command]
  3. If you have ssh installed, go to the next step.
    If you don't have ssh installed, install it now.
  4. List the contents of your ~/.ssh directory.
    If you don't have an .ssh directory, don't worry, you'll create it the Step 3 section.  If you have a .ssh directory or you may see something like this:

    myhost:~ manthony$ ls -a ~/.ssh

    If you have defined a default identity, you'll see the two id_* files:

    myhost:~ manthony$ ls -a ~/.ssh
    .        ..        id_rsa    known_hosts

    In this case, the default identity used RSA encryption ( If you want to use an existing default identity for your Bitbucket account, skip the next section and go to enable SSH compression for mercurial.

Step 3. Set up your default identity

By default, the system adds keys for all identities to the /Users/yourname/.ssh directory on Mac OSX, or /home/yourname/.ssh on Linux. This procedure creates a default identity. If you have a default identity and you want to use it for Bitbucket, skip this step and go to step 4.  If you have an existing default identity but you forgot the passphrase, you can also use this procedure to overwrite your default identity and create a fresh one.

Want to Use Multiple Identities?

You can create multiple SSH identities. Doing this is an advanced topic and beyond the scope of this tutorial. For information on how to create multiple identities, see Configure multiple SSH identities for GitBash, Mac OSX, & Linux.

Use the following procedure to create a new default identity.

  1. Open a terminal in your local system.
  2. Enter ssh-keygen at the command line.
    The command prompts you for a file where you want to save the key. If the .ssh directory doesn't exist, the system creates one for you.
  3. Press the Enter or Return key to accept the default location.
  4. Enter and re-enter a passphrase when prompted.
    Unless you need a key for a process such as script, you should always provide a passphrase. The command creates your default identity with its public and private keys. The whole interaction will look similar to the following:

    myhost:~ manthony$ ssh-keygen
    Generating public/private rsa key pair.
    Enter file in which to save the key (/Users/manthony/.ssh/id_rsa): 
    Created directory '/Users/manthony/.ssh'.
    Enter passphrase (empty for no passphrase): 
    Enter same passphrase again: 
    Your identification has been saved in /Users/manthony/.ssh/id_rsa.
    Your public key has been saved in /Users/manthony/.ssh/
    The key fingerprint is:
    4c:80:61:2c:00:3f:9d:dc:08:41:2e:c0:cf:b9:17:69 manthony@myhost.local
    The key's randomart image is:
    +--[ RSA 2048]----+
    |*o+ooo.          |
    |.+.=o+ .         |
    |. *.* o .        |
    | . = E o         |
    |    o . S        |
    |   . .           |
    |    .            |
    |                 |
    |                 |
  5. List the contents of ~/.ssh to view the key files.

    ls -a ~/.ssh

Step 4. Start the ssh-agent and load your keys

If you are running OSX 10.6.8 or later you can skip this step.  The OSX 10.6.8 system asks for your connection parameters the first time you try to establish a SSH connection.  Then, it automatically starts the ssh-agent for you.  If you don't have OSX 10.6.8 or are running another Linux operating system, do the following:

Open a terminal window and enter the ps -e | grep [s]sh-agent command to see if the agent is running:

myhost:~ manthony$ ps -e  | grep [s]sh-agent
 9060 ??         0:00.28 /usr/bin/ssh-agent -l

If the agent isn't running, start it manually with the following command:

myhost:~ manthony$ ssh-agent /bin/bash

Load your new identity into the ssh-agent management program using the ssh-add command.

$ ssh-add ~/.ssh/id_rsa
Enter passphrase for /Users/manthony/.ssh/id_rsa: 
Identity added: /Users/manthony/.ssh/id_rsa (/Users/manthony/.ssh/id_rsa)
myhost:~ manthony$ 

Use the ssh-add command to list the keys that the agent is managing.

$ ssh-add -l
2048 7a:9c:b2:9c:8e:4e:f4:af:de:70:77:b9:52:fd:44:97 /Users/manthony/.ssh/id_rsa (RSA)

Step 5. Enable SSH compression for Mercurial

When sending or retrieving data using SSH, Git does compression for you. Mercurial does not automatically do compression.  You should enable SSH compression as it can speed up things drastically, in some cases. To enable compression for Mercurial, do the following:

  1. Open a terminal window.
  2. Edit the Mercurial global configuration file (~/.hgrc).
  3. Add the following line to the UI section:

    ssh = ssh -C

    When you are done the file should look similar to the following:

    # Name data to appear in commits
    username = Emma <>
    ssh = ssh -C
  4. Save and close the file.

Step 6. Install the public key on your Bitbucket account

  1. From Bitbucket, choose avatar > Manage account from the application menu. 
    The system displays the Account settings page.
  2. Click SSH keys.
    The SSH Keys page displays. If you have any existing keys, those appear on this page.
  3. Back in your terminal window, copy the contents of your public key file.
    For example, in Linux you can cat the contents.

    $ cat ~/.ssh/

    In Mac OSX, the following command copies the output to the clipboard:

    $ pbcopy < ~/.ssh/
  4. Back in your browser, enter a Label for your new key, for example, Default public key.

  5. Paste the copied public key into the SSH Key field:
  6. Press Add key.
    The system adds the key to your account. Bitbucket sends you an email to confirm addition of the key. 

Step 7. Change your repo from HTTPS to the SSH protocol

The URL you use for a repo depends on which protocol you are using, HTTPS or SSH.  The Bitbucket repository Overview page has a quick way for you to see these URLS for your bb101repo  repo.  On the repo's Overview page look for the Clone button. 

Experiment for a moment, clicking back and forth between the SSH and the HTTPS protocol links to see how the URLs differ.  The table below shows the format for each DVCS based on protocol.

  SSH URL format HTTPS URL format
Mercurial ssh://




In the SSH format, the accountname appears after or In HTTPS format, the accountname before or

Make the change

Go to a terminal on your local system and navigate to your bb101repo-pratice repo. Then, do the following for Git and Mercurial:

Git users do this:

  1. View your current repo configuration.
    You should see something similar to the following:

    myhost:bb101repo-practice manthony$ cat .git/config
        repositoryformatversion = 0
        filemode = true
        bare = false
        logallrefupdates = true
        ignorecase = true
    [remote "origin"]
        fetch = +refs/heads/*:refs/remotes/origin/*
        url =
    [branch "master"]
        remote = origin
        merge = refs/heads/master

    As you can see, the url is using the HTTPS protocol.  There are a number of ways to change this value, the easiest way is just to edit the repo's configuration file.

  2. Edit the ~/repos/bb101repo-pratice/.git/config file with your favorite editor.
  3. Change the url value to use the SSH format for that repo.
    When you are done you should see something similar to the following:

    [remote "origin"]
        fetch = +refs/heads/*:refs/remotes/origin/*
        url =

Mercurial users do this:

  1. View your myquotefork repo configuration.
    You should see something similar to the following:

    myhost:.hg manthony$ cat hgrc
    default =
  2. Edit the ~/repos/myquotefork/.hg/hgrc file with your favorite editor.
  3. Change the default value to use the SSH format for that repo.
    When you are done you should see something similar to the following:

    default = ssh://
  4. Save and close the configuration file.

Step 8. Make a change under the new protocol

  1. Edit the README file in your bb101repo-practice repo.
  2. Add a new line to the file, for example:

    Welcome to My First Repo
    This repo is a practice repo I am using to learn bitbucket.
    You can access this repo with SSH or with HTTPS.
  3. Save and close the file.
  4. Add and then commit your change to your local repo.

    git add README
    git commit -m "making a change under the SSH protocol"
  5. Push your changes.
    The system warns  you that it is adding the Bitbucket host to the list of known hosts.

    myhost:bb101repo-practice manthony$ git push 
    Warning: Permanently added the RSA host key for IP address '' to the list of known hosts.
    Counting objects: 5, done.
    Delta compression using up to 4 threads.
    Compressing objects: 100% (2/2), done.
    Writing objects: 100% (3/3), 314 bytes, done.
    Total 3 (delta 1), reused 0 (delta 0)
    remote: bb/acl: newuserme is allowed. accepted payload.
       d3bb337..f0b152f  master -> master
  6. Open the repo Overview in Bitbucket to view your commit.

You are done!

You've completed this tutorial for Bitbucket. At this point, you should have a good beginners knowledge of what you can do in Bitbucket (You should also make sure you have checked to see your pull request changes incorporated.)  If you are a Mac user, you might want to see SourceTree a Free Git and Mercurial GUI (Mac OSX). Windows users can try Sourcetree Git GUI on Windows.

The rest of the documentation has more topics and information that can help you make the most of Bitbucket. Please let us know what you thought of this tutorial by logging an issue or by sending an email.  Of course, you can always contribute by commenting on or editing a page directly.

Was this helpful?

Thanks for your feedback!

74 Archived comments

  1. User avatar


    Pretty good intro. Thanks.

    13 Jan 2012
    1. User avatar


      You are most welcome.

      13 Jan 2012
  2. User avatar


    The intro is nicely explained. It was really easy for me to follow. Thanks!

    14 Jan 2012
    1. User avatar


      Thank you for the feedback. Glad to know it is working well.

      14 Jan 2012
  3. User avatar


    Excellent job ! Really very good starting point for your services. Keep going in this way (wink)

    29 Jan 2012
  4. User avatar


    Thank you. SSH is nice tool.

    06 Apr 2012
  5. User avatar


    Good job! Thank you!

    22 May 2012
  6. User avatar


    Great job on the tutorial.  Imagine that, they hired a writer to write(smile)

    The only thing that is missing for me is: what do I do if I already have code on my box that is not under source control?

    22 Jun 2012
    1. User avatar


      Bless me, you do know the way to a writer's heart.  Let's see, if you already have code but it isn't under source control, read this piece which I just created for you.


      22 Jun 2012
  7. User avatar


    Thank you sir! (heart) Bitbucket

    01 Oct 2012
    1. User avatar


      Well, Bitbucket says thank you — but you shouldn't assume the software is a man! ;-D

      01 Oct 2012
  8. User avatar


    SSH & BitBucket rocks!

    22 Nov 2012
  9. User avatar


    Hi, thanx for the great documentation.

    27 Nov 2012
  10. User avatar


    Thanks Mary

    28 Dec 2012
    1. User avatar


      You are welcome. Glad to help.

      28 Dec 2012
  11. User avatar


    Great tutorial!

    08 Jan 2013
    1. User avatar


      Thank you and welcome to BB.

      08 Jan 2013
  12. User avatar


    Very straight forward and easy to follow. Great! (smile)

    16 Mar 2013
  13. User avatar


    The documentation is really easy to follow! Great work! (smile)

    28 Mar 2013
  14. User avatar



    08 Apr 2013
  15. User avatar


    Thank you, Mary! simple, easy and thorough. Fantastic job!

    13 May 2013
  16. User avatar

    Justin Wilson

    This certainly helped. I hadn't been able to push any changes for some time, and somewhere along the lines, the SSH key ceased to work. It asked for a password, and regardless of changing passwords, it didn't work. So, I started from scratch and followed this tutorial. Thank you, Mary!

    18 Jun 2013
    1. User avatar


      You are welcome!

      18 Jun 2013
  17. User avatar

    vaibhav saini

    Great Tutorial. Thanks a lot for creating this.

    24 Jun 2013
  18. User avatar


    Thank you so much for the tutorial! It's awesome!

    11 Jul 2013
  19. User avatar


    Very detailed for beginners.  Perhaps have a leading section called "Basic Tutorial" like so:

     Click here to expand...

    1 - Set up your SSH Keys

    Open and run `ssh-keygen`.  Accept the default filepath and add your own password.

    2 - <Contents of Step 6 here>

    You're done!  

    There could then be an "Advanced Tutorial" with this article's body below.

    Better yet, a small downloadable app which, when run, performs these steps and synchronizes them to your BitBucket account, or some such tool to handle it for you.

    Thanks though for putting this together.

    20 Jul 2013
    1. User avatar


      Thanks for your comments.  The idea of a downloadable app is a good one; it has been brought up internally before. 

      21 Jul 2013
  20. User avatar


    Sweet! Great job!

    26 Jul 2013
  21. User avatar


    Not bad but far from usable for beginners. You don't mention what key algorithm you support nor the min/max length of them. You also seem to need a certain formatting of the key text to accept it, but do not reveal that anywhere!

    27 Jul 2013
    1. User avatar


      Hi! In Step 1, the third bullet we do mention which algorithms we support.   Selecting the algorithm provided by ssh-keygen is an advanced SSH topic so I don't cover it in our documentation.  I'm not aware of special formatting we require in the key. If you ran into issues, your can let me know what it was here or send an issue to

      29 Jul 2013
  22. User avatar

    Riinav G

    Very Nice walk through for setting up SSH, straight to the point and got my devHub ready...


    28 Jul 2013
  23. User avatar


    Awesome! Thank you very much!(smile)

    05 Aug 2013
  24. User avatar


    Sorry if this is heresy.  Can I use Git for Windows?

    06 Aug 2013
  25. User avatar


    oops, ok so you've already said "If you want set up on Microsoft Windows , we have instructions for Set up SSH for Git", thx!

    06 Aug 2013
  26. User avatar


    Thank you, i liked the tutorial, but i found it short.

    06 Sep 2013
  27. User avatar


    This is good. Thanks you very much!
    12 Oct 2013
  28. User avatar


    I like the tutorial was  little simple and well structured. I don't have any doubt right now =) 

    22 Oct 2013
  29. User avatar


    This was a great help to me by preventing my hair loss. Thanks!

    30 Oct 2013
    1. User avatar


      Love this!

      Bitbucket, our documentation proven to prevent hair loss.

      30 Oct 2013
  30. User avatar


    Followed these instructions and added my key, but I am getting the following when trying to connect to the repot or push or pull:

    ssh -Tv

    debug1: connect to address port 22: Connection refused

    debug1: Connecting to [] port 22.

    debug1: connect to address port 22: Connection refused

    ssh: connect to host port 22: Connection refused

    02 Nov 2013
    1. User avatar


      It appears you have run into a block connecting on port 22. See this page or speak with your system administrator if you are on a company network.

      03 Nov 2013
  31. User avatar


    Definitely one of the best tutorials I've ever use. It was very clearly laid out. Thank you!

    06 Nov 2013
    1. User avatar


      Way to make our day over here! Thanks. (big grin)

      06 Nov 2013
  32. User avatar


    What does DVCS mean?

    15 Nov 2013
    1. User avatar

      Marcus Bertrand [Atlassian]

      Distributed Version Control System

      15 Nov 2013
    1. User avatar


      The definition appears on the first page of tutorial. 

      15 Nov 2013
  33. User avatar


    I have to add my kudos. I've been wanting to get a handle on git for years, and this was great. I thought push/pulling a quote to a public page was ingenious, and this last ssh tutorial quickly filled in some holes in my newbie understanding of ssh.

    17 Nov 2013
  34. User avatar


    I think there might be a typo:

    [remote "origin"] fetch = +refs/heads/*:refs/remotes/origin/* url =


    Should be:
    [remote "origin"] fetch = +refs/heads/*:refs/remotes/origin/* url = ssh://git@bitbucket.

    At least that's what I needed to change to get things working.

    30 Dec 2013
  35. User avatar



    15 Jan 2014
  36. User avatar

    Chris Blackmon

    This really did help clear some things up for me. Pretty thorough beginner git tutorial in general, let alone just for Bitbucket.

    04 Feb 2014
  37. User avatar


    Very good beginner tutorial. Many thanks

    13 Feb 2014
  38. User avatar


    Great work guys, helped a lot. I had problems with Bitbucket because I couldn't add an SSH key before, I spent hours and it was giving me some weird errors even though I followed the instructions in the docs. 

    No this is much better and it worked finally (smile)

    16 Feb 2014
  39. User avatar

    Yitz Jacob

    awesome help – explained each step and I was able to do exactly what was necesary and it worked on the first try!  thanks soooo much!

    19 Feb 2014
  40. User avatar

    Mauricio Leyzaola

    Simply brilliant! Even myself could accomplish this tuto (tongue)


    05 Mar 2014
  41. User avatar


    help me please

    Permission denied (publickey).
    fatal: Could not read from remote repository.

    Please make sure you have the correct access rights


    when I clone a repo


    05 Mar 2014
  42. User avatar


    I met the same problem when I tried to set up a second machine (the first one works fine). When I tried to pull it says

    Permission denied (publickey).
    fatal: Could not read from remote repository.

    Please make sure you have the correct access rights



    11 Mar 2014
  43. User avatar


    In step 7:

    Instead of using
    url =

    you must use the following:

    url = ssh://
    16 Mar 2014
    1. User avatar

      Stephane Gosselin

      Thank-you so much. Please update the docs I had to do this step to get things working!

      13 Jun 2014
      1. User avatar

        Dan Stevens [Atlassian]

        Thanks for commenting I'm running back through this today and will update the doc later this afternoon.

        23 Jun 2014
  44. User avatar


    The fact that i can't get this working, and I had github setup in 5 minutes, is mind boggling. 

    20 Mar 2014
  45. User avatar


    I followed the instructions here, everything seemed to work great. When I logged out of my server and back in, I got a publickey error when I try to ssh. Trial and error showed I had to redo step 4.

    ssh-agent /bin/bash;

    ssh-add ~/.ssh/id_rsa

    ... got it working again, but I can't figure out how to make that permanent on ubuntu. After re-logging in ...

    ps -e | grep [s]sh-agent

    ... shows nothing

      Any ideas?

    23 Mar 2014
  46. User avatar


    I followed the instructions here, everything seemed to work great. When I logged out of my server and back in, I got a publickey error when I try to ssh. Trial and error showed I had to redo step 4.

    ssh-agent /bin/bash;

    ssh-add ~/.ssh/id_rsa

    ... got it working again, but I can't figure out how to make that permanent on ubuntu. After re-logging in ...

    ps -e | grep [s]sh-agent

    ... shows nothing

      Any ideas?

    23 Mar 2014
    1. User avatar


      Sorry for opening this case again, but I had the same issue here.

      Struggled a lot of time to figure out how to avoid this error since the docs to instantiate the ssh-agent are everyone different from each other. In the end I killed all the ssh-agent running with:

      Re-opened the terminal and started a new ssh-agent process with

      Then everything worked like a charm.


      BTW, a little useful addition, since people (me first) complain about typing the passphrase every time, could be to tell how to insert it into your OS keychain. It works perfectly on OS X, for Linux I think that a little more Googling is needed. Anyway, it works only if your keychain is unlocked:

      30 Apr 2015
  47. User avatar

    Strahinja Stankovic

    I got the error:

    ssh-agent error “Could not open a connection to your authentication agent.”

    so the magic was in using:

    exec ssh-agent bash

    if bash is your shell. I`ve found this on Stackoverflow forum, reported on CentOS and solved my issue on Debian, so I guess it would be helpful.

    15 Jul 2014
    1. User avatar

      Dan Stevens [Atlassian]

      Thanks for taking the time to comment! I am always looking for better ways to help people get SSH set up successfully.

      I'll run back through a few times and see if I can improve with some of the variations.

      Have an exceptional day!

      15 Jul 2014
    1. User avatar


      Same here. Had to use '$ exec ssh-agent bash'

      Tip found here:

      22 Jan 2015
  48. User avatar

    Rosemary McCloskey

    There are too many hoops to go through to get editing permissions, but the first line of section 3,

    "By default, the system adds keys for all identities to the /Users/yourname/.ssh directory."

    should be

    "By default, the system adds keys for all identities to the /Users/yourname/.ssh directory on Mac OS/X, or /home/yourname/.ssh on Linux."

    There is no /Users directory on Linux.

    06 Aug 2014
  49. User avatar

    Pelle Mårtenson

    I don t find the file cat .git/config

    I found a .gitconfig though. But it does´t contain the info listed above. Just info about [user]. What do I do wrong?

    05 Mar 2015
    1. User avatar

      Dan Stevens [Atlassian]

      Hello Pelle,

      Just a quick question: when you run the command:

      are you in the top level directory of the repository? 

      It's a mistake I've made in the past, even when checking through the tutorial I have helped write.

      Oh, another potential is that you might be working through the mercurial side of things and those commands are for a Git repository. It's a bug in this portion of the tutorial (sad) that the two paths converge here and I've got it in my back log to separate them.

      I will take another run through this later and see what else it might be.

      Thanks for taking the time to post.

      Happy coding,



      05 Mar 2015
  50. User avatar

    Pelle Mårtenson

    Aha! Thanks. I was in the wrong directory. Do I have to do this step with every project then? My file look correct to me. It says:

    [remote "origin"]
    url =
    fetch = +refs/heads/*:refs/remotes/origin/*

    But when I try to push I get this message.

    "conq: repository does not exist. fatal: Could not read from remote repository.

    Please make sure you have the correct access rights and the repository exists."

    I have two keys installed on Bitbucket. Can that be a part om my problem?

    Thanks a lot for help! Appreciate it.


    06 Mar 2015
  51. User avatar

    Robert Lilly

    I've followed the tutorial and everything appears to be working except for the fact that it still asks for the passphrase for the key every time I try to push or pull. I thought the whole point of using SSH keys was to eliminate the need for entering a password every time. Am I misunderstanding or did I do something wrong?

    BTW, I'm using Git and the local machine is running Linux, in case that matters.


    08 Mar 2015
  52. User avatar

    Pelle Mårtenson

    My last problem was only a misspelld username!

    10 Mar 2015
  53. User avatar

    Benyong Shi

    The SSH Key should always be added to personal account managment right? 

    However, there is also "SSH Keys" tab in team management page? How does it work? 

    And also the "Change Password" in team management page is also very confusing...

    03 Jun 2015
  54. User avatar

    Elijah Bee

    Worked perfectly!!

    Thank you 

    03 Jul 2015
Powered by Confluence and Scroll Viewport