Configure multiple SSH identities for GitBash, Mac OSX, & Linux

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.

SSH Command Purpose
ssh-keygen Creates key pairs.
ssh-agent Agent for providing keys to remote servers. The agent holds loaded keys in memory.
ssh-add Loads a private key into the agent.

To support multiple SSH identities in Bitbucket Cloud, do the following:

Create multiple identities for Mac OSX, GitBash, and Linux

You should at this point already have created at least a single default identity. To see if you have a default identity already, list the contents of your .ssh directory. Default identity files appear as a id_encrypt and pair. The encrypt value is either rsa or dsa. Use the ssh-keygen command to create a new identity. In the example below, the identity is named personalid.

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

If you have multiple Bitbucket accounts, you need to generate a new public/private key pair for each account.

Create a SSH config file

When you have multiple identity files, create a SSH config file mechanisms to create aliases for your various identities. You can construct a SSH config file using many parameters and different approaches. The format for the alias entries use in this example is:

Host alias
IdentityFile ~/.ssh/identity

To create a config file for two identities (workid and personalid), you would do the following:

  1. Open a terminal window.
  2. Edit the ~/.ssh/config file.
    If you don't have a config file, create one.
  3. Add an alias for each identity combination for example:

    Host workid
     IdentityFile ~/.ssh/workid
    Host personalid
     IdentityFile ~/.ssh/personalid
  4. Close and save the file.

Now, you can substitute the alias for portions of the repository URL address as illustrated in the following table:

DVCS Default address Address with alias


Mercurial ssh:// ssh://hg@alias/username/reponame/

There are lots of ways to use SSH aliasing. Another common use case may be the situation where you are using Bitbucket and GitHub on the same machine. The codingbadger suggested the following configuration for that use case:

# Default GitHub user
 PreferredAuthentications publickey
 IdentityFile ~/.ssh/personalid
# Work user account
 PreferredAuthentications publickey
 IdentityFile ~/.ssh/workid

If you google for "ssh aliases" or "ssh aliasing" you may find examples that suit you needs better.

Configure 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 = Emma <>
    ssh = ssh -C
  4. Save and close the file.

Load each key into the appropriate Bitbucket account

You load each identities public key into corresponding account. If you have multiple Bitbucket accounts, you load each account with the corresponding public key you created. If you have an account with a repository you access from two identities, you can load two keys into that account – one for each identity. Use the following procedure to load each key into your Bitbucket accounts:

  1. From Bitbucket Cloud, 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/

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

    $ pbcopy < ~/.ssh/
  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. 

Ensure the ssh-agent is running and loaded with your keys

Most modern operating systems (and GitBash) start a ssh-agent running for you. However, it is important you know how to check for a running agent and start one if necessary.

  1. Open a terminal window and enter the appropriate command for your operating system.

    GitBash Mac OSX andLinux
    $ ps | grep ssh-agent
    5192  1  5192    5192  ? 500 19:23:34 /bin/ssh-agent

    If for some reason the agent isn't running, start it by entering eval ssh-agent at the command line. You should only be running a single instance of ssh-agent. If you have multiple instances running, use the kill PID command to stop each of them. Then, restart a single instance.

    $ ps -e | grep [s]sh-agent
     9060 ??     0:00.28 /usr/bin/ssh-agent -l

    If the agent isn't running, start it by hand. The format for starting the command manually is:

    $ eval ssh-agent $SHELL

    $SHELL is the environment variable for your login shell.

  2. List the currently loaded keys:

  3. If necessary, add your new key to the list:

  4. List the keys again to verify the add was successful:

Clone a repository using SSH and your alias configuration

To clone a repository with one of multiple SSH identities that you configured, you clone the repo and using your alias in the SSH URL.  To try this for yourself, log into Bitbucket and do the following:

  1. Navigate to the repository Overview.
  2. Display the SSH URL.
    For example, Bitbucket displays its tutorial URL as:
    hg clone ssh://
  3. Open a terminal window on your system.

  4. Navigate to the directory where you store your repositories.

  5. Enter the command but substitute your config alias appropriately.

    For example, if you want to use your personalid alias to enter the clone you enter:

    hg clone ssh://hg@personalid/tutorials/

    The system clones the repository for you.

  6. Change directory to the repository.

  7. Display the contents of the repository's configuration. 

    $ cat .hg/hgrc 
    default = ssh://hg@tutorials/tutorials/

    Notice that the DVCS stored the URL you used for the clone; the URL that includes your alias. Now, moving forward for this repository, the DVCS uses the URL that includes the SSH alias.

Change existing repositories from HTTPS to SSH (optional)

You can change existing repository configurations to use a SSH configuration that makes use of your multiple identities. You'll only need to do this for repositories that you have already cloned with HTTPS or for repositories where you want to change an existing SSH specification. For example, if you used SSH to clone a repository in the past and now want to set it up to use another SSH key.

Git configuration

  1. Open a terminal window.
  2. Navigate to the repository configuration file (REPO_INSTALLDIR/.git).

  3. Open the config file with your favorite editor.

  4. Locate the url value in the [remote "origin"] section

    [remote "origin"]
      fetch = +refs/heads/*:refs/remotes/origin/*
      url =

    In this example, the url is using the HTTPS protocol. 

  5. Change the url value to use the SSH format for your repository.
    When you are done you should see something similar to the following:

    [remote "origin"]
      fetch = +refs/heads/*:refs/remotes/origin/*
      url = git@personalid:newuserme/bb101repo.git

Mercurial Configuration

  1. Open a terminal window.
  2. Navigate to the repository configuration file (REPO_INSTALLDIR/.hg).

  3. Open the hgrc file with your favorite editor.

    default =
  4. Change the [paths] default to:

    default = ssh://
  5. Save and close the file.

 My thanks to the codingbadger and to Charles on the Bitbucket team who helped me get my head around this technique. Any errors here are of my own making of course.

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

25 Archived comments

  1. User avatar


    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

    18 Dec 2012
  2. User avatar


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

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

    User git
    IdentityFile ~/.ssh/keyname

    and used in .git/config:

    [remote "origin"]
    url = ssh://
    26 Jan 2013
    1. User avatar


      Thanks. This helped a lot.

      13 Nov 2013
  3. User avatar


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

              IdentityFile ~/.ssh/youridentityfile

    Works fine.lked

    02 Feb 2013
  4. User avatar


    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.


    13 Mar 2013
    1. User avatar


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

      13 Mar 2013
  5. User avatar


    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
    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 [] port 22.
    debug1: connect to address port 22: Connection timed out
    debug1: Connecting to [] port 22.
    debug1: connect to address port 22: Connection timed out
    ssh: connect to host port 22: Connection timed out



    13 Mar 2013
  6. User avatar


    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.


    13 Mar 2013
    1. User avatar


      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.

      13 Mar 2013
      1. User avatar

        Henry Scullion

        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!

        27 Jan 2014
  7. User avatar


    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.

    13 Mar 2013
    1. User avatar


      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.

      13 Mar 2013
  8. User avatar


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

    13 Mar 2013
  9. User avatar


    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

    27 Jun 2013
    1. User avatar


      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 

      01 Jul 2013
  10. User avatar


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

    Let's say my repository address as reported is

    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??

    10 Sep 2013
    1. User avatar


      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.

      10 Sep 2013
  11. User avatar

    Clint M

    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.

    11 Apr 2014
  12. User avatar

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

    22 Apr 2014
    1. User avatar

      Dan Stevens [Atlassian]

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

      	     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) 

      22 Apr 2014
      1. User avatar

        Chris Beck

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

        22 Apr 2014
    1. User avatar

      Chris Beck

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

      07 Jun 2014
      1. User avatar

        Dan Stevens [Atlassian]

        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.

        10 Jun 2014
        1. User avatar

          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


          10 Jun 2014
  13. User avatar

    Michael 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
    26 Apr 2015
Powered by Confluence and Scroll Viewport