Set up SSH for Mercurial

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 communicates with the Bitbucket server. 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.

Set up SSH

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.

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.

The following sections cover how to set up SSH for Mercurial.

  Set up SSH for Windows

Step 1. Install TortoiseHg

TortoiseHg is the Microsoft Windows version of Mercurial. If you haven't installed Mercurial yet, installing TortoiseHg automatically gives you Mercurial. If you have installed Mercurial, TortoiseHg allows you to set up SSH and give you another option in place of the command line.

After you download the all-in-one installer (MSI version) and install it, you may need to restart your system for the installation to take effect.

Step 2. Install PuTTYgen and configure PuTTY

PuTTYgen is a free RSA and DSA key generation tool that you also use when setting up SSH.

  1. Download the proper version of the utilities for your system – each one is a single executable file.
  2. Move the puttygen.exe executable to the C:\Program Files\TortoiseHg folder.
  3. Start Putty.
    The PuTTy Configuration dialog displays. Use this dialog to configure your PuTTy sessions. 
  4. Under the Session node, select Default Settings and press Load.
    This allows you to edit the Default Settings session configuration. 
  5. Under the Connection node, click SSH.
     The Options controlling SSH connections display.
  6. Check Enable compression.
    This option can improve performance of a low-band connection. 
  7. Click the Session node, select Default Settings and press Save.
     
  8. Click the Close button (red x).

Step 3. Create your default identity

The following procedure creates a default identity with PuttyGen. If you have an existing private key, you can skip this step and go onto  Enable SSH compression for Mercurial.

  1. Locate the puttygen.exe executable 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 4. 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 = Emma Paris <emmap1@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 5. 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 6. 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 7. 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 format

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

HTTPS URL format https:// accountname @bitbucket.org/ accountname / reponame

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

Go 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 8. Make a change under the new protocol

  1. Edit the Index.html file in your 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.
  Set up SSH for Mac OS/Linux

Step 1. Ensure you have an SSH client installed

SSH is most likely included with your version of Mac OS or Linux. To make sure, do the following to verify your installation:

  1. From your terminal window, enter the following command, which identifies the version of SSH you have installed.
    If SSH is installed, you see something similar to the following:

    $ 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]

    If you have ssh installed, go to the next step. 
    If you don't have ssh installed, install it now.

  2. List the contents of your ~/.ssh directory.
    If you don't have an .ssh directory, don't worry, you'll create it the next section. If you have a .ssh directory or you may see something like this:

    $ ls -a ~/.ssh
    known_hosts

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

    $ ls -a ~/.ssh
    .        ..        id_rsa        id_rsa.pub    known_hosts

    In this case, the default identity used RSA encryption (id_rsa.pub). If you want to use an existing default identity for your Bitbucket account, skip the next section and go to start the ssh-agent and load your keys.

Step 2. 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  start the ssh-agent and load your keys. 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.

    $ ssh-keygen
    Generating public/private rsa key pair.
    Enter file in which to save the key (/Users/emmap1/.ssh/id_rsa):
  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:

    $ ssh-keygen
    Generating public/private rsa key pair.
    Enter file in which to save the key (/Users/emmap1/.ssh/id_rsa):
    Created directory '/Users/emmap1/.ssh'.
    Enter passphrase (empty for no passphrase):
    Enter same passphrase again:
    Your identification has been saved in /Users/emmap1/.ssh/id_rsa.
    Your public key has been saved in /Users/emmpa1/.ssh/id_rsa.pub.
    The key fingerprint is:
    4c:80:61:2c:00:3f:9d:dc:08:41:2e:c0:cf:b9:17:69 emmpa1@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 3. 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:

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

    $ ps -e | grep [s]sh-agent
     9060 ?? 0:00.28 /usr/bin/ssh-agent -l
  2. If the agent isn't running, start it manually with the following command:

    $ ssh-agent /bin/bash


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

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


  4. 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 4. 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:

    [ui]
    # Name data to appear in commits
    username = Emma <emmap1@atlassian.com>
    ssh = ssh -C
  4. Save and close the file.

Step 5. 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/id_rsa.pub

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

    $ pbcopy < ~/.ssh/id_rsa.pub
  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 6. 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 Clone button of the BitbucketSpaceStation repository has a quick way for you to see these URLS.

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 based on protocol.

SSH URL format

ssh://hg@bitbucket.org /< accountname>/<reponame>

HTTPS URL format https://<accountname>@bitbucket.org/< accountname>/<reponame>

To make the change, go to a terminal on your local system and navigate to your bitbucketspacestation repo. Then, do the following:

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

    $ cd ~/repos/bitbucketspacestation
    $ cat .hg/hgrc
    [paths]
    default = https://emmap1@bitbucket.org/emmap1/bitbucketspacestation

    As you can see, the default URL is using the HTTPS protocol.

  2. Open the ~/repos/bitbucketspacestation/.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:

    [paths]
    default = ssh://hg@bitbucket.org/emmap1/bitbucketspacestation

    Save and close the configuration file.

Step 7. Make a change under the new protocol

  1. From the local directory of your bitbucketspacestation repository, create a new file called readme.txt.
  2. Add the following text to the README.txt file:

    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.

    $ hg add README
    $ hg 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.

    $ hg push
    Warning: Permanently added the RSA host key for IP address '207.223.240.182' to the list of known hosts.
    pushing to ssh://hg@bitbucket.org/emmap1/bitbucketspacestation
    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: emmap1 is allowed. accepted payload.
  6. Open the repo Overview in Bitbucket to view your commit.

Was this helpful?

Thanks for your feedback!

Powered by Confluence and Scroll Viewport