Typically, if you are working with multiple accounts and/or multiple machines, you benefit from creating multiple SSH identities. In Mac OS X, GitBash, and Linux you can use the three ssh- commands to create and manage your identities.
|Creates key pairs.|
|Agent for providing keys to remote servers. The agent holds loaded keys in memory.|
|Loads a private key into the agent.|
To support multiple SSH identities in , do the following:
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.pub pair. The
encrypt value is either
dsa. Use the
ssh-keygen command to create a new identity. In the example below, the identity is named
If you have multiple Bitbucket accounts, you need to generate a new public/private key pair for each account.
When you have multiple identity files, consider creating an SSH
config file 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 used in this example is:
To create a config file for two identities (workid and personalid), you would do the following:
configfile, create one.
Add an alias for each identity combination for example:
Host workid HostName bitbucket.org IdentityFile ~/.ssh/workid Host personalid HostName bitbucket.org IdentityFile ~/.ssh/personalid
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|
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 Host github.com HostName github.com PreferredAuthentications publickey IdentityFile ~/.ssh/personalid # Work user account Host bitbucket.org HostName bitbucket.org PreferredAuthentications publickey IdentityFile ~/.ssh/workid
If you google for "ssh aliases" or "ssh aliasing" you may find examples that suit you needs better.
Load each public key into the corresponding account. 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:
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
Back in your browser, enter a Label for your new key, for example,
Default public key.
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.
Open a terminal window and enter the appropriate command for your operating system.
|GitBash||Mac OS X andLinux|
If for some reason the agent isn't running, start it by entering
If the agent isn't running, start it by hand. The format for starting the command manually is:
$ eval ssh-agent $SHELL
List the currently loaded keys:
If necessary, add your new key to the list:
List the keys again to verify the add was successful:
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:
hg clone ssh://email@example.com/tutorials/tutorials.bitbucket.org
Open a terminal window on your system.
Navigate to the directory where you store your repositories.
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/tutorials.bitbucket.org
The system clones the repository for you.
Change directory to the repository.
Display the contents of the repository's configuration.
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.
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.
Navigate to the repository configuration file (
config file with your favorite editor.
url value in the
[remote "origin"] section
[remote "origin"] fetch = +refs/heads/*:refs/remotes/origin/* url = https://firstname.lastname@example.org/newuserme/bb101repo.git
In this example, the
url is using the HTTPS protocol.
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
Navigate to the repository configuration file (
hgrc file with your favorite editor.
[paths] default = https://email@example.com/newuserme/bb101repo
[paths] default to:
[paths] default = ssh://firstname.lastname@example.org/newuserme/bb101repo
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.