Skip to end of metadata
Go to start of metadata

If you are following the tutorial, you have already set up your Git repositories to use SSH. This page has you set up your Mercurial repositories to use SSH as well. If you skipped the Git instructions, you missed the explanation of basic SSH concepts.   

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.

GitBash, Linux, or Mac User?

This page shows you how to set up and use a single default SSH identity on Windows for a Mercurial repository. If you want set up for a Git repository on Windows using GitBash, there are instructions for Set up SSH for Git. Finally, if you are working on Mac OSX or Linux, a single set of instructions shows you how to setup and identity for both Git or Mercurial in these environments.

Step 1. Check if you have existing default identity

TortoiseHG relies on the PuTTYgen utility to generate an identity. If you are following along in this tutorial, you should have already installed PuTTYgen. If you used PuTTYgen in the past to generate an identity, you should have an identity.ppk file on your system. If you have an existing private key, you can skip Step 2 below and go onto Enable SSH compression for Mercurial. Otherwise, continue to the next step.

Step 2. Create your default identity

The following procedure creates a default identity with PuttyGen.  PuttyGen generates keys in its own format.  So, rather than re-use the file you created for use within GitBash, you'll create a different key for TortoiseHG.

  1. Locate the puttygen.exe executaible in your system and double click the icon to start it.
    If you are following along with this tutorial, you installed PuTTYgen in C:\Program Files\TortoiseHG. The system opens the PuTTY Key Generator dialog.
  2. Complete
  3. Press Generate.
    Following the instructions to generate some randomness.

    When the generation completes, the system displays the public key and a number of other fields.
  4. Enter and confirm a key passphrase.
  5. Press Save private key.
    The system prompts you for a location to save the file and a file name. By convention, store your key files in a folder called C:\Users\yourname\.ssh. and give it a .ppk extension.
  6. Go ahead and close PuTTYgen.

Step 3. Enable SSH compression for Mercurial

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

  1. Start the TortoiseHg Workbench.
  2. Select File > Settings.
  3. Make sure you have the global settings tab selected.
  4. Press Edit File.
  5. Add the following line to the UI section:

    ssh = "TortoisePlink.exe" -ssh -2 -batch -C

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

    [ui]
    # Name data to appear in commits
    username = Mary Anthony <manthony@atlassian.com>
    ssh = "C:\Program Files\TortoiseHg\TortoisePlink.exe" -ssh -2 -batch -C
  6. Press Save to store your settings and close the file.
  7. Press OK to close the settings dialog.

Step 4. Start Pageant and install your private key

TortoiseHG comes with Pageant which is an SSH authentication agent. You load your keys into Pageant and it automatically authenticates you so you don't need to enter your passphrase. Do the following to load your keys:

  1. Start Pageant by double clicking its icon.
    By default, TortoiseHG installs the Pageant in the C:\Program Files\TortoiseHG folder. When it is running, Pageant appears in your system tray:
  2. Double-click the Pageant icon to launch the Pagent Key List dialog.
  3. Click the Add Key button.
    The system displays the Select Private Key File dialog.
  4. Navigate to and open the default key you created previously.
  5. Enter the passphrase when prompted:
  6. Press OK.
    Pageant shows your key in the running list.
  7. Press Close to close the dialog.
    Pageant continues to run on your system.

Step 5. Install the public key on your Bitbucket account

  1. Open a browser and log in to Bitbucket.
  2. Choose avatar > Account from the menu bar.
    The system displays the Account settings page.
  3. Click SSH keys.
    The SSH Keys page displays. It shows a list of any existing keys. Then, below that, a dialog for labeling and entering a new key.
  4. Switch to your local desktop and start the PuTTYgen program.
  5. Press Load.
  6. Navigate to and open your default private key.
  7. Enter your passphrase when prompted and press OK.
    The system displays your public key.
  8. Select and copy the contents of the Public key for pasting into OpenSSH authorized_keys file field.
  9. Back in your browser, enter a Label for your new key, for example, Default public key.
  10. Paste the copied public key into the SSH Key field:
  11. Press Add key.
    The system adds the key and it appears in the SSH Keys listing.
  12. Close PuTTYgen.

Step 6. Configure your local repository to use the SSH protocol

The URL you use for a repository depends on which protocol you are using, HTTPS and SSH. The Bitbucket repository Overview page has a quick way for you to see the one for your myquotefork repository. On the repository's Overview page look for the Clone this repository line. Experiment for a moment, click 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
Mercurialssh://hg@bitbucket.org/accountname/reponame/

https://accountname@bitbucket.org/accountname/reponame

Git

git@bitbucket.org:accountname/reponame.git

or

ssh://git@bitbucket.org/accountname/reponame.git

https://accountname@bitbucket.org/accountname/reponame.git

In the SSH format, the accountname appears after git@bitbucket.org or hg@bitbucket.org. In HTTPS format, the accountname before git@bitbucket.org or hg@bitbucket.org.

Got to your local system and navigate to your myquotefork repository (the only Mercurial repository you've worked with so far). These instructions assume you have added the repository to the TortoiseHG Workbench.

  1. Start TortoiseHG.
  2. Right click your myquotefork repository and choose Settings.
    The system displays the TortoiseHG Settings dialog with the myquotefork repository settings tab active.
  3. Press Edit File.
  4. View your current repository configuration.
    You should see something similar to the following:

    [paths]
    default = https://bitbucket.org/newuserme/myquotefork
  5. Change the default value to use the SSH format for that repository.
    When you are done you should see something similar to the following:

    [paths]
    default = ssh://hg@bitbucket.org/newuserme/myquotefork
  6. Press Save to close the editor.

  7. Press OK to close the settings dialog.
  8. Restart TortoiseHG Workbench so that it uses the new SSH setting.

Step 7. Make a change under the new protocol

  1. Edit the Index.html file in your myquotefork repository.
  2. Add a new line to the file.

  3. Save and close the file.
  4. Add and then commit your change to your local repository.

  5. Push your changes to your fork.
    A successful push shows in your TortoiseHG log as follows:

    pushing to ssh://hg@bitbucket.org/newuserme/myquotefork
    searching for changes
    remote: adding changesets
    remote: adding manifests
    remote: adding file changes
    remote: added 1 changesets with 1 changes to 1 files
    remote: bb/acl: newuserme is allowed. accepted payload.
    [command completed successfully Mon Dec 19 10:49:06 2011]
    myquotefork

    PuTTY may warn you that the host key is not yet stored. If that happens, press Yes to add the bitbucket.org host key.

  6. Open the repository Overview in Bitbucket to view your commit.

Next Steps

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 https://tutorials.bitbucket.org 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.

31 Comments

  1. Anonymous

    This tutorial is indeed very helpful! Two thumbs up! Thanks!

  2. Anonymous

    Great tutorial, very clear and concise - thanks!

  3. Anonymous

  4. Anonymous

    You may skip the Pageant step if you put the path to the ssh key on the global settings.

    Just have it like this instead:

    [ui]
    # Name data to appear in commits
    username = Mary Anthony <manthony@atlassian.com>
    ssh = "C:\Program Files\TortoiseHg\TortoisePlink.exe" -ssh -2 -batch -C -i C:\Users\<YourAccount>\.ssh\private.ppk
    1. Hi,

      I take your point. I was aware of that method.  I'll see about adding it to our SSH guide.  For beginners, I tend to err on the side of showing the moving parts. There are a couple of reasons for this. First I like a beginner to reach the gross understanding of the component parts of any thing I'm teaching. Second, implementing an advanced method where the mechanism is hidden in a tool's configuration file, is much simpler to explain once a reader has the gross understanding. Later, if that beginner  needs to debug a situation, they are better able to troubleshoot.

      Mary

    2. Anonymous

      By doing it this way without Pageant, you must enter your passphrase for every time.

    3. Anonymous

      This was exactly what I was looking for, thanks.

      I found that the full path tp TortoisePlink.exe was not needed, and %USERPROFILE% can be used in place of C:\Users\<YourAccount> thus:

      ssh = "TortoisePlink.exe" -ssh -2 -batch -C -i %USERPROFILE%\.ssh\private.ppk

       

       

  5. Anonymous

    Brilliant!!

  6. Anonymous

    As good as I hoped when I started.  Thanks–your bosses should give you a raise!!!

  7. Actually I was able to get that working. I'm not entirely sure what the issue was, but I realized on GitBash I had about 13 ssh-agent processes running. So I killed all those, and went through the entire setup again and was finally able to get it working.

    1. I'm glad you got it sorted Cody.  

  8. Anonymous

    Needed to update the global settings path for Program files when using 64bit windows 8

     

    ssh = "C:\Program Files\TortoiseHg\TortoisePlink.exe" -ssh -2 -batch -C

     


     

    1. It still asks for credentials (user/password) in command line and in Tortoise workbench as well. Using 64bit Windows 7.

  9. Anonymous

    Thanks!, nice tutorial for a newbie like me.

    but when I push from TortoiseHg al last step, I have this output log:

    remote: conq: not an hg repository.
    no suitable response from remote hg

    I searched in google but I not found a good explanation for this error log :$

    u know? ty

    1. Anonymous

      Check that our repository type is of Mercurial type.  If you accidentally created a repository for Git, you will obtain this error.

  10. Anonymous

    This is a great tutorial but when trying to push data to bitbucket from tortoisehg, this error appears:

    "Disconnected: No supported authentication methods available (server sent: publickey)"

    Do you have any idea how to fix this?

    Thanks

    1. Make sure Paegent is running and that your key is installed.

  11. Anonymous

    In step 4, I tried to use the private key that I had created for use with git (id_rsa) using ssh-keygen. Pageant wouldn't accept it. I had to create a separate key pair for use with Hg using PuttyGen. Do ssh-keygen and puttygen use two different and incompatible private key formats?

    Lars

    1. PuttyGen uses its own format.  You'll need convert it. Here is a good article for that. http://meinit.nl/using-your-openssh-private-key-in-putty.  

  12. Anonymous

    P.S. if so, it would be helpful in step 4 to say explicitly that you can't use the private key that you generated in "Set up SSH for Git".

    1. Point taken. I added it to the tutorial in Step 2 when I ask people to create a new identity.

  13. Working through the BB101 tutorial I successfully got SSH to work on the Git repository. Following the next step to get the same access for Hg repositories I was not so successful. I have access to BB according to ssh:

    Mark@CAPTAINNEMO ~
    $ ssh -T hg@bitbucket.org
    logged in as mstega2.

    You can use git or hg to connect to Bitbucket. Shell access is disabled.

    Mark@CAPTAINNEMO ~
    $

    I tried both a new PPK generation and a conversion of the key created when enabling SSH for Git. I've added the private key to Pageant and the public key to BB.

    When I try to use the SSH connection to BB from the TortoiseHG Workbench I get a PuTTY Fatal Error - Server refused to start a shell/command. The log contains:

    % hg --repository S:\Solutions\OHI\bb101-QuoteFork push ssh://hg@bitbucket.org/mstega2/ms-tutorialquotefork
    pushing to ssh://hg@bitbucket.org/mstega2/ms-tutorialquotefork
    no suitable response from remote hg
    [command returned code 255 Wed Sep 18 13:15:50 2013]
    bb101-QuoteFork%

    I am able to access the repository using HTTPS, just not SSH. I'm not certain where/how to further investigate. Any suggestions are welcome. 

    1. Hmm, have you tried deleting all the keys on BB. Then, just testing with the Paegent generated PPK? (Reducing the variables a bit.)

       

      1. I just tried that - No change

        I started over from the very beginning (removed/reinstalled TortoiseHg). I don't know what the issue was, but it is gone now; I added Pageant to the Windows start folder (you run shell:startup with Win+R) with the path to the key as a parameter so it starts upon logon (easier than adding the key each time you start Pagaent).

        I do understand why you wanted to use PuttyGen to create a new key pair but if you do that then the name of the key in Step 5 should be different than the name used in the Git SSH tutorial.

        1. Mark glad you got it sorted.  You caught bug in the doc. I'm reusing the screen capture for uploading the key to Bitbucket so the label shows up the same in both.  I'll fix that.  Thank you for the catch.

  14. Anonymous

    I don't quite get it why I need to set-up both Git and Mercurial, from what it seems having only one is enough ...

    1. Well, you don't have to do anything. (big grin) Since the tutorial is an introduction to Bitbucket and Bitbucket supports both DVCS platforms, I ask you to install both. You never know when you might encounter some cool Mercurial repo.

      Course, if you absolutely know you'll never touch Mercurial. Just skip those bits that ask you to do things with it.  

    2. Depending on how you plan to use Bitbucket, it may be a smart idea to have both available to you. There are many projects out there only in Mercurial or only in Git. It is just the same as probably wanting subversion installed. It only takes a small effort to install, with a big time savings when you need them.

  15. Anonymous

    Thanks very much for a great tutorial! I'm a newbie programmer and never would have figured this out without your tutorial.

  16. While following the steps in this tutorial i receive an error while trying to push edited index.html file.

    Command:

    pushing to ssh://hg@bitbucket.org/elkhand/myquotefork

    Error:

    no suitable response from remote hg
    [command returned code 255

    If anyone has faced this problem, please kindly share the solution.

    Thank you very much in advance.