robotsnoindex

While using the same password on multiple sites makes your accounts less secure, most of the time you can use the same SSH key for multiple accounts. However, there are specific situations when you'll need to set up more than one SSH key:

  • You have two different Bitbucket Cloud accounts. For example, if you have a work-related Bitbucket account and a personal Bitbucket account, each account must have its own SSH key.
  • You're using two different computers to log in to the same account.
  • You want to execute DVCS actions on a repository with a script that uses a public key with an empty passphrase, allowing it to run without human intervention.

Here are your options when setting up additional SSH keys:


WindowsmacOSLinux
Git

Command line prompt / Git Bash

Sourcetree

Terminal

Terminal
MercurialSourcetree

Terminal

Terminal

By this point, you should have already created at least one SSH key. This one SSH key is your default identity because it's the key that Bitbucket checks first when authenticating. If you don't have an SSH key, follow the steps on Set up an SSH key.

Set up additional SSH keys for Git

When using Git, you can use this section to create as many SSH keys as you need on Windows, macOS, or Linux.

Step 1. Prepare your default identity

  1. Determine your Git clone URL.

    $ git remote -v
    origin git@bitbucket.org:teamsinspace/bitbucketspacestation.git     (fetch)
    origin git@bitbucket.org:teamsinspace/bitbucketspacestation.git     (push)

  2. Update the remote URL with your Bitbucket username by replacing git@bitbucket.org with <username>@bitbucket.org. For this step and the ones that follow, enter your username in place of <username>.

    $ git remote set-url origin <username>@bitbucket.org:teamsinspace/bitbucketspacestation.git

Step 2. Create additional SSH keys

You'll need to create an additional SSH key for each extra Bitbucket account you have or each computer you use. For example, if you have four Bitbucket accounts, you need to generate 3 new SSH keys, meaning you'll have 4 keys in all.

  1. Generate your new SSH key. In place of <username>, enter the username of the Bitbucket account for which you're creating the SSH key.

    For Windows 7 or earlier

    You can only enter ssh-keygen into the Git Bash window. It won't work in the Command prompt.

    $ ssh-keygen -f ~/.ssh/<username>
    Generating public/private rsa key pair.
    Enter passphrase (empty for no passphrase):
    Enter same passphrase again:
    Your identification has been saved in /Users/<username>/.ssh/<username>.
    Your public key has been saved in /Users/<username>/.ssh/<username>.pub.
    The key fingerprint is:
    7a:9c:b2:9c:8e:4e:f4:af:de:70:77:b9:52:fd:44:97 <username>
    The key's randomart image is:
    +--[ RSA 2048]----+
    |         |
    |         |
    |        .|
    |        Eo|
    |  .  S  . ..|
    |  . . o . ... .|
    |  . = = ..o o |
    |  . o X ... . .|
    |  .ooB.o ..  |
    +-----------------+

  2. Add your new SSH key to your account. Make sure you're adding it to the right account.

    $ ssh-add ~/.ssh/<username>

Step 3. Add the public key to your Account settings

Add each public SSH key into the corresponding account. If you have an account that you access from two different locations, add both keys to that account.

  1. From Bitbucket, choose Personal settings from your avatar in the lower left.

    The Account settings page opens.

  2. Click SSH keys.

    The SSH keys page displays. If you have any existing keys, those appear on this page.

  3. Copy the contents of your public key file.

    • Windows: Open your ~/.ssh/<public_key> file and copy its contents.

    • macOS: Copy the output to the clipboard with this command: $ pbcopy < ~/.ssh/<public_key_file>

    • Linux: Copy the output to the clipboard with this command: $ cat ~/.ssh/<public_key_file>

  4. From Bitbucket, enter a Label for your new key, for example, Public key #2.

  5. Paste the copied public key into the SSH Key field:

  6. Click Save.

    Bitbucket sends you an email to confirm the addition of the key.

Next time you clone a repository, use the SSH URL for that repository and replace git in the <username>@bitbucket.org part of the URL with your Bitbucket username. For example:

git clone <username>@bitbucket.org:teamsinspace/bitbucketspacestation.git

If you want to change the URL of an existing repository using HTTPS or a different SSH URL, change the remote URL for your repository.

Set up additional SSH keys for Mercurial (on macOS and Linux)

Use this section to create all additional keys for Mercurial or Linux. While you can use Sourcetree to generate your first SSH key on macOS, you must use the terminal to create additional keys.

Step 1. Prepare your default identity

  1. Open the .hg/hgrc file and locate your Mercurial clone URL at the default value.

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

  2. Update the remote URL with your Bitbucket username by replacing hg@bitbucket.org with <username>@bitbucket.org. For this step and the ones that follow, enter your username in place of <username>.

    [paths] default = ssh://<username>@bitbucket.org/teamsinspace/bitbucketspacestation

Step 2. Create additional SSH keys

You'll need to create an additional SSH key for each extra Bitbucket account you have or each computer you use. For example, if you have four Bitbucket accounts, you need to generate 3 new SSH keys, meaning you'll have 4 keys in all.

  1. Generate your new SSH key. In place of <username>, enter the username of the Bitbucket account for which you're creating the SSH key.

    For Windows 7 or earlier

    You can only enter ssh-keygen into the Git Bash window. It won't work in the Command prompt.

    $ ssh-keygen -f ~/.ssh/<username>
    Generating public/private rsa key pair.
    Enter passphrase (empty for no passphrase):
    Enter same passphrase again:
    Your identification has been saved in /Users/<username>/.ssh/<username>.
    Your public key has been saved in /Users/<username>/.ssh/<username>.pub.
    The key fingerprint is:
    7a:9c:b2:9c:8e:4e:f4:af:de:70:77:b9:52:fd:44:97 <username>
    The key's randomart image is:
    +--[ RSA 2048]----+
    |         |
    |         |
    |        .|
    |        Eo|
    |  .  S  . ..|
    |  . . o . ... .|
    |  . = = ..o o |
    |  . o X ... . .|
    |  .ooB.o ..  |
    +-----------------+

  2. Add your new SSH key to your account. Make sure you're adding it to the right account.

    $ ssh-add ~/.ssh/<username>

Step 3. (Mercurial only) Enable SSH compression

Enabling SSH compression is recommended but not required.

By default, Git automatically performs compression when sending or retrieving data, but Mercurial doesn't. Enabling SSH compression can speed up sending and retrieving data, drastically in some cases.

To enable SSH compression:

  1. Open the Mercurial global configuration file (~/.hgrc).

  2. Add this line to the UI section:

    ssh = ssh -C

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

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

Step 4. Add the public key to your Account settings

Add each public SSH key into the corresponding account. If you have an account that you access from two different locations, add both keys to that account.

  1. From Bitbucket, choose Personal settings from your avatar in the lower left.

    The Account settings page opens.

  2. Click SSH keys.

    If you've already added keys, you'll see them on this page.

  3. In your terminal window, copy the contents of your public key file.

    • Mac OSX: Copy the output to the clipboard with this command: $ pbcopy < ~/.ssh/<public_key_file>

    • Linux: Copy the output to the clipboard with this command: $ cat ~/.ssh/<public_key_file>

  4. From Bitbucket, enter a Label for your new key, for example, Public key #2.

  5. Paste the copied public key into the SSH Key field:

  6. Click Save.

    Bitbucket sends you an email to confirm the addition of the key.

Next time you clone a repository, use the SSH URL for that repository and replace hg in the <username>@bitbucket.org part of the URL with your Bitbucket username. For example:

hg clone ssh://<username>@bitbucket.org/teamsinspace/bitbucketspacestation

If you want to change the URL of an existing repository using HTTPS or a different SSH URL, change the remote URL for your repository.

Set up additional SSH keys with Sourcetree (on Windows)

Whether you use Git or Mercurial, use this section to create as many SSH keys as you need when using Sourcing on Windows.

Step 1. Create an SSH key

  1. From Tools, select Create or Import SSH Keys.

  2. From the PuTTY Key Generator dialog, click the Generate button.

  3. As the SSH key generates, hover your mouse over the blank area in the dialog. It may take a minute or two.

    When SSH key generation is complete, you see the public key and a few other fields.

  4. Update the Key comment with something that distinguishes it from your other SSH keys.

  5. Enter a passphrase for your SSH key in the Key passphrase and Confirm passphrase fields.

  6. Click Save public key. From the save dialog, choose where to save your public key, name the file, and click Save.

  7. Click Save private key. From the save dialog, choose where to save your private key, name the file, and click Save.

  8. Close the PuTTY Key Generator dialog.

Step 2. (Mercurial only) Enable SSH compression

Enabling SSH compression is recommended but not required. You'll need to clone and open a Mercurial repository to complete these steps.

By default, Git automatically performs compression when sending or retrieving data, but Mercurial doesn't. Enabling SSH compression can speed up sending and retrieving data, drastically in some cases.

To enable SSH compression:

  1. Click Settings in the top right of the repository window.
    The repository settings may open to the Remotes tab. If not, click the Remotes tab.
  2. Click Edit Config File to open the Mercurial global configuration file (~/.hgrc).

  3. Add this line to the UI section:

    ssh = ssh -C

    When you're done the file should look similar to this:

    [ui]
# name and email (local to this repository, optional), e.g.
username = Emma <emmap1@atlassian.com>
ssh = ssh -C

  4. Save and close the file.

Step 3. Install your private key on Pageant

Sourcetree comes with an SSH authentication agent called Pageant. Load your private key into Pageant to automatically authenticate so that you don't need to enter your passphrase.

  1. Double-click the Pageant (PuTTY Authentication Agent) icon in your system tray to open the Pageant Key List dialog.

  2. Click the Add Key button.

    The system displays the Select Private Key File dialog.

  3. Navigate to the private key file you saved in Step 1 and click Open.

  4. Enter the passphrase for your SSH key and click OK.

    Pageant shows your key in the running list.

  5. Press Close to close the dialog.

Step 4. Add the public key to your Account settings

  1. From Sourcetree, open the PuTTY Key Generator dialog by going to Tools > Create or Import SSH Keys.

  2. Click Load, navigate to your SSH folder, and click the private key.

  3. Enter your passphrase for the SSH key and click OK.

  4. Copy the public key in the first field.

  5. From Bitbucket, choose Personal settings from your avatar in the lower left.

    The Account settings page opens.

  6. Click SSH keys.

    If you've already added keys, you'll see them on this page.

  7. Click Add key.

  8. From Bitbucket, enter a Label for your new key, for example, Public key #2.

  9. Paste the copied public key into the SSH Key field.

  10. Click Save.
    Bitbucket sends you an email to confirm the addition of the key.

    Edit an SSH key

    After you add a key, you can edit the key's Label but not the key itself. If you need to change the key's contents, you must delete and re-add the key.

25 Comments

  1. Anonymous

    I think it's important to show multiple accounts in the example - this is kinda dropped after step one. I believe this is where the difference of opinion might lie -> it would make sense to clone from an alias if you, indeed, have an alias set up in the .ssh/config file

  2. Anonymous

    Address with alias git@alias:accountname/reponame.git did not worked for me (osx).

    After googling around i did that in : ~/.ssh/config 

    Host somename.bitbucket.org
     HostName bitbucket.org
     User git
     IdentityFile ~/.ssh/keyname

    and used in .git/config:

    [remote "origin"]
     url = ssh://somename.bitbucket.org/myUserName/myRepoName.git

    1. Anonymous

      Thanks. This helped a lot.

  3. Anonymous

    The minimal usable format for the SSH config file on the Mac is

        Host bitbucket.org
              IdentityFile ~/.ssh/youridentityfile

    Works fine.lked

  4. Anonymous

    I have not been able to get a 2nd identity to work.  I started on one Linux machine, followed the procedures for defining and setting up a default ID and everything worked fine.  Then on a different Linux system I generated a key pair for a different ID, I tried to follow the procedures where, but have been unable to gain access to Bitbucket via ssh on the 2nd Linux.  On the 1st Linux system it still works accessing Bitbucket via ssh.

     

    1. m

      The issue is hard to diagnose without more information. You can first try the suggestions on our Troubleshooting SSH Issues. If that doesn't solve your problem, please send a support issue to support@bitbucket.org. Include in your issue, your accountname, the repo you are trying to access with SSH.  The command you enter to connect and any information returned by the command.

  5. Anonymous

    Thanks for the troubleshooting link.  Here is some of what I'm seeing:

    $ ssh-add -l

    2048 "What looks like a valid key" /home/tabberta/.ssh/atabbert (RSA)

    $ ssh -v hg@bitbucket.org
    OpenSSH_4.3p2, OpenSSL 0.9.8e-fips-rhel5 01 Jul 2008
    debug1: Reading configuration data /home/tabberta/.ssh/config
    debug1: Reading configuration data /etc/ssh/ssh_config
    debug1: Applying options for *
    debug1: Connecting to bitbucket.org [207.223.240.182] port 22.
    debug1: connect to address 207.223.240.182 port 22: Connection timed out
    debug1: Connecting to bitbucket.org [207.223.240.181] port 22.
    debug1: connect to address 207.223.240.181 port 22: Connection timed out
    ssh: connect to host bitbucket.org port 22: Connection timed out

     

     

  6. Anonymous

    I guess that's a fingerprint that's shown, not the key, my mistake.  Anyway it is correct.

    I am unclear on how Bitbucket knows which saved ssh key to verify the incoming request with.  Specifically, how does it distinguish between a request from the "default" ID on one system, from a named ID on another system.  It is rather confusing.

    Thanks

    1. m

      Are you trying to connect to the same Bitbucket account from two different computers with two different keys? You'll need to make sure you have uploaded each public key from each system to your Bitbucket account.  Your account will show two keys.

      You can also just copy the .ssh from the working system to the second computer. In which case, the same key connects you from both and your account will show a single key.  Copying can be tricky though so google instructions for your OS.

      1. henscu

        This question really helped me as I want to log in to the same Bitbucket account from a Macbook and also a Windows PC. From the first line of the tutorial above I understood that I needed to set up and manage two identities:

        Typically, if you are working with multiple accounts and/or multiple machines, you benefit from creating multiple SSH identities. In Mac OSX, GitBash, and Linux you can use the three ssh- commands to create and manage your identities.

        If I had not read these comments before starting I would have wasted a lot of time, though being able to manage multiple identities is a very useful skill.

        I will now just set up a default identity for my Macbook and copy the private key to my Windows PC.

        It would be great to add a line to explicitly cover this case at the top of the tutorial to save people from unnecessary work.

        Thanks again for your fantastically detailed tutorials!

  7. Anonymous

    Thanks for the quick response!

    Yes to the 1st question, same Bitbucket account, from two different computers, with two different keys.  I got the impression that I must do it this way because my login ID is different on the two computers.

    If that doesn't matter, I will copy my .ssh directory from the working system to the other and remove the non-working key from Bitbucket.

    1. m

      SSH is "identity based authentication." It relies on the key/passphrase and isn't associated with the user account on the machine:

      You place a copy of the identity public key into the file $HOME/.ssh/authorized_keys on any account you wish to enable access using this key.

      This is the complete explanation.

  8. Anonymous

    Thank you!  I will give this a try, probably tomorrow.  That makes sense.

  9. Anonymous

    Unlike the rest This important  tutorial is extremely convoluted with steps that dont work in achieving the final goal and not explaning why do we exactly do those steps

    1. m

      This is a pretty advanced topic.  If you want a beginners guide, please work through the beginners guide here: Set up SSH for Git -- deprecated.   I'd be happy to address any specific issues you have with this page if you want to email support@bitbucket.org. 

  10. Anonymous

    Examples are somewhat unclear. Could somebody give me an example please:

    Let's say my repository address as reported is git@bitbucket.org:someuser/someproject.git

    I have an ssh-agent running that has a key:

    4096 <...> /home/user/.ssh/workid (RSA)

    What is the URL I should use with git clone using these settings??

    1. m

      Bitbucket always displays for you the URL on the repo Overview page.

      The Clone button will give you the entire command for cloning.  How you configured your SSH key locally does not impact your choices of URL.

  11. CM

    On Mac you can use ssh-add -K [path to your private key] to persist the addition of the second key and store the passphrase in the os x keychain.

  12. Chris Beck

    What if I'm going through an extra machine using ssh-agent forwarding?

    • I've got my local Mac where I have 2 host aliases for bitbucket.org defined in ~/.ssh/config
      • Each host has it's own key and everything works peachy
    • I've got my remote Unix server where I don't want my keys stored so I use ssh-add
      • If I type ssh-add -l on the server then I see both keys being forwarded
        • However, the git repo on the server only wants to use the first key on the list
      • I tried creating a ~/.ssh/config on the server but that didn't work
        • I'm wondering of I'm specifying the IdentityFile correctly on the server:
          • IdentityFile ~/.ssh/bitbucket_ccmcbeck_rsa

    Thanks for any help

    1. Daniel Stevens

      Hummm... I'm not sure I have the answer to this Chris. I would think it would see both identities in sequence:

           IdentityFile
	     Specifies a file from which the user's RSA or DSA authentication
	     identity is read.	The default is ~/.ssh/identity for protocol
	     version 1, and ~/.ssh/id_rsa and ~/.ssh/id_dsa for protocol ver-
	     sion 2.  Additionally, any identities represented by the authen-
	     tication agent will be used for authentication.  The file name
	     may use the tilde syntax to refer to a user's home directory.  It
	     is possible to have multiple identity files specified in configu-
	     ration files; all these identities will be tried in sequence.

       

      You can try emailing the support team while I look for a better answer. SSH is something this writer is still getting up to snuff on. (smile) 

      1. Chris Beck

        Thanks Dan.  Perhaps I can see more of what's going on using ssh -v.

    2. Chris Beck

      Still having this problem, so I posted a more detailed description on Superuser

      1. Daniel Stevens

        I liked your post so I remember to follow it, not that I like your still having this problem. I'll try to devote some research time to this myself as well.

        1. Chris Beck

          Then you'll notice that I was able to solve the issue by:

          • Creating a ~/.ssh/config on the intermediate server to declare the aliases for that server
            • Include the IdentitiesOnly yes property so sshd won't try all my forwarded keys
          • Copy the .pub (only!) version of my keypair on the intermediate server so it can figure out which private key on my local computer to authenticate against

           

  13. m_reeves

    When adding the key on a Mac, you can add the -K flag to permanently add the key to your Keychain.

    $ ssh-add -K ~/.ssh/workid