Skip to end of metadata
Go to start of metadata

Up until this point, you have been using the secure hypertext transfer protocol (HTTPS) to communicate between your local system and Bitbucket. When you use HTTPS, you need to authenticate (supply a username and password) each time you take an action that communicates with the Bitbucket server. You can specify the username in the DVCS configuration file; you don't want to store your password there though where anyone can see it. So, this means you must manually type a password when you use HTTPS with  your local repository. 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.


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 and for Set up SSH for Mercurial

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
               [-I pkcs11] [-i identity_file]
               [-L [bind_address:]port:host:hostport]
               [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.  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 to save the key in. If the .ssh directory doesn't exist, the system creates one for you.
  3. 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 = Mary Anthony <>
    ssh = ssh -C
  4. Save and close the file.


Step 6. Install the public key on your Bitbucket account

  1. Open a browser and log into Bitbucket.
  2. Choose avatar > Manage Account from the application menu. 
    The system displays the Account settings page.
  3. Click SSH keys.
  4. 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/
  5. Back in your browser, enter a Label for your new key, for example, Default public key.

  6. Paste the copied public key into the SSH Key field:
  7. 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 formatHTTPS URL format




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

Make the change

Got 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"]
        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"]
        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.

    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 
    Counting objects: 5, done.
    Delta compression using up to 4 threads.
    Writing objects: 100% (3/3), 314 bytes, done.
    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 the 101 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.


  1. Anonymous

    Pretty good intro. Thanks.

    1. You are most welcome.

  2. Anonymous

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

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

  3. Anonymous

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

  4. Anonymous

    Thank you. SSH is nice tool.

  5. Anonymous

    Good job! Thank you!

  6. Anonymous

    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?

    1. 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.


  7. Anonymous

    Thank you sir! (heart) Bitbucket

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

  8. Anonymous

    SSH & BitBucket rocks!

  9. Anonymous

    Hi, thanx for the great documentation.

  10. Anonymous

    1. You are welcome. Glad to help.

  11. Anonymous

    Great tutorial!

    1. Thank you and welcome to BB.

  12. Anonymous

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

  13. Anonymous

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

  14. Anonymous

  15. Anonymous

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

  16. 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!

  17. Great Tutorial. Thanks a lot for creating this.

  18. Anonymous

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

  19. Anonymous

    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.

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

  20. Anonymous

    Sweet! Great job!

  21. Anonymous

    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!

    1. 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

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


  23. Anonymous

    Awesome! Thank you very much!(smile)

  24. Anonymous

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

  25. Anonymous

    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!

  26. Anonymous

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

  27. Anonymous

    This is good. Thanks you very much!
  28. Anonymous

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

  29. Anonymous

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

    1. Love this!

      Bitbucket, our documentation proven to prevent hair loss.

  30. Anonymous

    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

    1. 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.

  31. Anonymous

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

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

  32. Anonymous

    What does DVCS mean?

    1. Distributed Version Control System

    2. The definition appears on the first page of tutorial. 

  33. Anonymous

    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.

  34. Anonymous

    I think there might be a typo:



    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.

  35. Anonymous

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

  37. Anonymous

    Very good beginner tutorial. Many thanks

  38. Anonymous

    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)

  39. 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!

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


  41. Anonymous

    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


  42. Anonymous

    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