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.
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.
- Locate the
puttygen.exeexecutaible 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.
- 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.
- Enter and confirm a key passphrase.
- 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
- 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:
- Start the TortoiseHg Workbench.
- Select File > Settings.
- Make sure you have the global settings tab selected.
- Press Edit File.
Add the following line to the UI section:
When you are done the file should look similar to the following:
- Press Save to store your settings and close the file.
- 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:
- Start Pageant by double clicking its icon.
By default, TortoiseHG installs the Pageant in the
C:\Program Files\TortoiseHGfolder. When it is running, Pageant appears in your system tray:
- Double-click the Pageant icon to launch the Pagent Key List dialog.
- Click the Add Key button.
The system displays the Select Private Key File dialog.
- Navigate to and open the default key you created previously.
- Enter the passphrase when prompted:
- Press OK.
Pageant shows your key in the running list.
- Press Close to close the dialog.
Pageant continues to run on your system.
Step 5. Install the public key on your Bitbucket account
- Open a browser and log in to Bitbucket.
- Choose avatar > Account from the menu bar.
The system displays the Account settings page.
- 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.
- Switch to your local desktop and start the PuTTYgen program.
- Press Load.
- Navigate to and open your default private key.
- Enter your passphrase when prompted and press OK.
The system displays your public key.
- Select and copy the contents of the Public key for pasting into OpenSSH authorized_keys file field.
- Back in your browser, enter a Label for your new key, for example,
Default public key.
- Paste the copied public key into the SSH Key field:
- Press Add key.
The system adds the key and it appears in the SSH Keys listing.
- 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 format||HTTPS URL format|
In the SSH format, the
accountname appears after
email@example.com. In HTTPS format, the
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.
- Start TortoiseHG.
- Right click your
repository and choose Settings.
The system displays the TortoiseHG Settings dialog with the myquotefork repository settings tab active.
- Press Edit File.
View your current repository configuration.
You should see something similar to the following:
defaultvalue to use the SSH format for that repository.
When you are done you should see something similar to the following:
Press Save to close the editor.
- Press OK to close the settings dialog.
- Restart TortoiseHG Workbench so that it uses the new SSH setting.
Step 7. Make a change under the new protocol
- Edit the
Index.htmlfile in your
Add a new line to the file.
- Save and close the file.
Add and then commit your change to your local repository.
Push your changes to your fork.
A successful push shows in your TortoiseHG log as follows:
PuTTY may warn you that the host key is not yet stored. If that happens, press Yes to add the bitbucket.org host key.
- Open the repository Overview in Bitbucket to view your commit.
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.